tksbrokerapi.TKSBrokerAPI

   1# -*- coding: utf-8 -*-
   2# Author: Timur Gilmullin
   3
   4"""
   5**TKSBrokerAPI** is the trading platform for automation and simplifying the implementation of trading scenarios,
   6as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways:
   7from the console, it has a rich keys and commands, or you can use it as Python module with `python import`.
   8
   9TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive
  10the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.
  11
  12- **Open account for trading:** http://tinkoff.ru/sl/AaX1Et1omnH
  13- **TKSBrokerAPI module documentation:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
  14- **See examples:** https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
  15- **Used constants are in the TKSEnums module:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
  16- **About Tinkoff Invest API:** https://tinkoff.github.io/investAPI/
  17- **Tinkoff Invest API documentation:** https://tinkoff.github.io/investAPI/swagger-ui/
  18"""
  19
  20# Copyright (c) 2022 Gilmillin Timur Mansurovich
  21#
  22# Licensed under the Apache License, Version 2.0 (the "License");
  23# you may not use this file except in compliance with the License.
  24# You may obtain a copy of the License at
  25#
  26#     http://www.apache.org/licenses/LICENSE-2.0
  27#
  28# Unless required by applicable law or agreed to in writing, software
  29# distributed under the License is distributed on an "AS IS" BASIS,
  30# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31# See the License for the specific language governing permissions and
  32# limitations under the License.
  33
  34
  35import sys
  36import os
  37from argparse import ArgumentParser
  38from importlib.metadata import version
  39
  40from datetime import datetime, timedelta
  41from dateutil.tz import tzlocal, tzutc
  42from time import sleep
  43
  44import re
  45import json
  46import requests
  47import traceback as tb
  48from typing import Union
  49
  50from multiprocessing import cpu_count
  51from multiprocessing.pool import ThreadPool
  52import pandas as pd
  53
  54from TKSEnums import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  55
  56from pricegenerator.PriceGenerator import PriceGenerator, uLogger  # This module has a lot of instruments to work with candles data. See docs here: https://github.com/Tim55667757/PriceGenerator
  57from pricegenerator.UniLogger import DisableLogger as PGDisLog  # Method for disable log from PriceGenerator
  58
  59import UniLogger as uLog  # Logger for TKSBrokerAPI
  60
  61
  62# --- Common technical parameters:
  63
  64PGDisLog(uLogger.handlers[0])  # Disable 3-rd party logging from PriceGenerator
  65uLogger = uLog.UniLogger  # init logger for TKSBrokerAPI
  66uLogger.level = 10  # debug level by default for TKSBrokerAPI module
  67uLogger.handlers[0].level = 20  # info level by default for STDOUT of TKSBrokerAPI module
  68
  69__version__ = "1.5"  # The "major.minor" version setup here, but build number define at the build-server only
  70
  71CPU_COUNT = cpu_count()  # host's real CPU count
  72CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
  73
  74# --- Main constants:
  75
  76NANO = 0.000000001  # SI-constant nano = 10^-9
  77
  78
  79def NanoToFloat(units: str, nano: int) -> float:
  80    """
  81    Convert number in nano-view mode with string parameter `units` and integer parameter `nano` to float view. Examples:
  82
  83    `NanoToFloat(units="2", nano=500000000) -> 2.5`
  84
  85    `NanoToFloat(units="0", nano=50000000) -> 0.05`
  86
  87    :param units: integer string or integer parameter that represents the integer part of number
  88    :param nano: integer string or integer parameter that represents the fractional part of number
  89    :return: float view of number
  90    """
  91    return int(units) + int(nano) * NANO
  92
  93
  94def FloatToNano(number: float) -> dict:
  95    """
  96    Convert float number to nano-type view: dictionary with string `units` and integer `nano` parameters `{"units": "string", "nano": integer}`. Examples:
  97
  98    `FloatToNano(number=2.5) -> {"units": "2", "nano": 500000000}`
  99
 100    `FloatToNano(number=0.05) -> {"units": "0", "nano": 50000000}`
 101
 102    :param number: float number
 103    :return: nano-type view of number: `{"units": "string", "nano": integer}`
 104    """
 105    splitByPoint = str(number).split(".")
 106    frac = 0
 107
 108    if len(splitByPoint) > 1:
 109        if len(splitByPoint[1]) <= 9:
 110            frac = int("{}{}".format(
 111                int(splitByPoint[1]),
 112                "0" * (9 - len(splitByPoint[1])),
 113            ))
 114
 115    if (number < 0) and (frac > 0):
 116        frac = -frac
 117
 118    return {"units": str(int(number)), "nano": frac}
 119
 120
 121def GetDatesAsString(start: str = None, end: str = None) -> tuple:
 122    """
 123    Create tuple of date and time strings with timezone parsed from user-friendly date.
 124
 125    User dates format must be like: `%Y-%m-%d`, e.g. `2020-02-03` (3 Feb, 2020).
 126
 127    Example input: "2022-06-01" "2022-06-20" -> output: ("2022-06-01T00:00:00Z", "2022-06-20T23:59:59Z")
 128    An error exception will occur if input date has incorrect format.
 129
 130    If `start=None`, `end=None` then return dates from yesterday to the end of the day.
 131    If `start=some_date_1`, `end=None` then return dates from `some_date_1` to the end of the day.
 132    If `start=some_date_1`, `end=some_date_2` then return dates from start of `some_date_1` to end of `some_date_2`.
 133    Start day may be negative integer numbers: `-1`, `-2`, `-3` - how many days ago.
 134
 135    Also, you can use keywords for start if `end=None`:
 136    `today` (from 00:00:00 to the end of current day),
 137    `yesterday` (-1 day from 00:00:00 to 23:59:59),
 138    `week` (-7 day from 00:00:00 to the end of current day),
 139    `month` (-30 day from 00:00:00 to the end of current day),
 140    `year` (-365 day from 00:00:00 to the end of current day),
 141
 142    :return: tuple with 2 strings `(start, end)` dates in UTC ISO time format `%Y-%m-%dT%H:%M:%SZ` for OpenAPI.
 143             See date and time format here: `TKSEnums.TKS_DATE_TIME_FORMAT`.
 144             Example: `("2022-06-01T00:00:00Z", "2022-06-20T23:59:59Z")`. Second string is the end of the last day.
 145    """
 146    uLogger.debug("Input start day is [{}] (UTC), end day is [{}] (UTC)".format(start, end))
 147    s = datetime.now(tzutc()).replace(hour=0, minute=0, second=0, microsecond=0)  # start of the current day
 148    e = s.replace(hour=23, minute=59, second=59, microsecond=0)  # end of the current day
 149
 150    # time between start and the end of the current day:
 151    if start is None or start.lower() == "today":
 152        pass
 153
 154    # from start of the last day to the end of the last day:
 155    elif start.lower() == "yesterday":
 156        s -= timedelta(days=1)
 157        e -= timedelta(days=1)
 158
 159    # week (-7 day from 00:00:00 to the end of the current day):
 160    elif start.lower() == "week":
 161        s -= timedelta(days=6)  # +1 current day already taken into account
 162
 163    # month (-30 day from 00:00:00 to the end of current day):
 164    elif start.lower() == "month":
 165        s -= timedelta(days=29)  # +1 current day already taken into account
 166
 167    # year (-365 day from 00:00:00 to the end of current day):
 168    elif start.lower() == "year":
 169        s -= timedelta(days=364)  # +1 current day already taken into account
 170
 171    # -N days ago to the end of current day:
 172    elif start.startswith('-') and start[1:].isdigit():
 173        s -= timedelta(days=abs(int(start)) - 1)  # +1 current day already taken into account
 174
 175    # dates between start day at 00:00:00 and the end of the last day at 23:59:59:
 176    else:
 177        s = datetime.strptime(start, "%Y-%m-%d").replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=tzutc())
 178        e = datetime.strptime(end, "%Y-%m-%d").replace(hour=23, minute=59, second=59, microsecond=0, tzinfo=tzutc()) if end is not None else e
 179
 180    # converting to UTC ISO time formatted with Z suffix for Tinkoff Open API:
 181    s = s.strftime(TKS_DATE_TIME_FORMAT)
 182    e = e.strftime(TKS_DATE_TIME_FORMAT)
 183
 184    uLogger.debug("Start day converted to UTC ISO format, with Z: [{}], and the end day: [{}]".format(s, e))
 185
 186    return s, e
 187
 188
 189class TinkoffBrokerServer:
 190    """
 191    This class implements methods to work with Tinkoff broker server.
 192
 193    Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/
 194
 195    About `token`: https://tinkoff.github.io/investAPI/token/
 196    """
 197    def __init__(self, token: str, accountId: str = None, useCache: bool = True, defaultCache: str = "dump.json") -> None:
 198        """
 199        Main class init.
 200
 201        :param token: Bearer token for Tinkoff Invest API. It can be set from environment variable `TKS_API_TOKEN`.
 202        :param accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports.
 203                          Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.
 204        :param useCache: use default cache file with raw data to use instead of `iList`.
 205                         True by default. Cache is auto-update if new day has come.
 206                         If you don't want to use cache and always updates raw data then set `useCache=False`.
 207        :param defaultCache: path to default cache file. `dump.json` by default.
 208        """
 209        if token is None or not token:
 210            try:
 211                self.token = r"{}".format(os.environ["TKS_API_TOKEN"])
 212                uLogger.debug("Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/")
 213
 214            except KeyError:
 215                uLogger.error("`--token` key or environment variable `TKS_API_TOKEN` is required! See https://tinkoff.github.io/investAPI/token/")
 216                raise Exception("Token required")
 217
 218        else:
 219            self.token = token  # highly priority than environment variable 'TKS_API_TOKEN'
 220            uLogger.debug("Bearer token for Tinkoff OpenAPI set up from class variable `token`")
 221
 222        if accountId is None or not accountId:
 223            try:
 224                self.accountId = r"{}".format(os.environ["TKS_ACCOUNT_ID"])
 225                uLogger.debug("Main account ID [{}] set up from environment variable `TKS_ACCOUNT_ID`".format(self.accountId))
 226
 227            except KeyError:
 228                uLogger.warning("`--account-id` key or environment variable `TKS_ACCOUNT_ID` undefined! Some of operations may be unavailable (overview, trading etc).")
 229
 230        else:
 231            self.accountId = accountId  # highly priority than environment variable 'TKS_ACCOUNT_ID'
 232            uLogger.debug("Main account ID [{}] set up from class variable `accountId`".format(self.accountId))
 233
 234        self.version = __version__  # duplicate here used TKSBrokerAPI main version
 235        """Current TKSBrokerAPI version: major.minor, but the build number define at the build-server only.
 236
 237        Latest version: https://pypi.org/project/tksbrokerapi/
 238        """
 239
 240        self.aliases = TKS_TICKER_ALIASES
 241        """Some aliases instead official tickers.
 242
 243        See also: `TKSEnums.TKS_TICKER_ALIASES`
 244        """
 245
 246        self.aliasesKeys = self.aliases.keys()  # re-calc only first time at class init
 247
 248        self.exclude = TKS_TICKERS_OR_FIGI_EXCLUDED  # some tickers or FIGIs raised exception earlier when it sends to server, that is why we exclude there
 249
 250        self.ticker = ""
 251        """String with ticker, e.g. `GOOGL`. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc. More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 252
 253        See also: `SearchByTicker()`, `SearchInstruments()`.
 254        """
 255
 256        self.figi = ""
 257        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`.
 258
 259        See also: `SearchByFIGI()`, `SearchInstruments()`.
 260        """
 261
 262        self.depth = 1
 263        """Depth of Market (DOM) can be >= 1. Default: 1. It used with `--price` key to showing DOM with current prices for givens ticker or FIGI.
 264
 265        See also: `GetCurrentPrices()`.
 266        """
 267
 268        self.server = r"https://invest-public-api.tinkoff.ru/rest"
 269        """Tinkoff REST API server for real trade operations. Default: https://invest-public-api.tinkoff.ru/rest
 270
 271        See also: API method https://tinkoff.github.io/investAPI/#tinkoff-invest-api_1 and `SendAPIRequest()`.
 272        """
 273
 274        uLogger.debug("Broker API server: {}".format(self.server))
 275
 276        self.timeout = 15
 277        """Server operations timeout in seconds. Default: `15`.
 278
 279        See also: `SendAPIRequest()`.
 280        """
 281
 282        self.headers = {
 283            "Content-Type": "application/json",
 284            "accept": "application/json",
 285            "Authorization": "Bearer {}".format(self.token),
 286            "x-app-name": "Tim55667757.TKSBrokerAPI",
 287        }
 288        """Headers which send in every request to broker server. Please, do not change it! Default: `{"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}"}`.
 289
 290        See also: `SendAPIRequest()`.
 291        """
 292
 293        self.body = None
 294        """Request body which send to broker server. Default: `None`.
 295
 296        See also: `SendAPIRequest()`.
 297        """
 298
 299        self.moreDebug = False
 300        """Enables more debug information in this class, such as net request and response headers in all methods. `False` by default."""
 301
 302        self.historyFile = None
 303        """Full path to the output file where history candles will be saved or updated. Default: `None`, it mean that returns only Pandas DataFrame.
 304
 305        See also: `History()`.
 306        """
 307
 308        self.htmlHistoryFile = "index.html"
 309        """Full path to the html file where rendered candles chart stored. Default: `index.html`.
 310
 311        See also: `ShowHistoryChart()`.
 312        """
 313
 314        self.instrumentsFile = "instruments.md"
 315        """Filename where full available to user instruments list will be saved. Default: `instruments.md`.
 316
 317        See also: `ShowInstrumentsInfo()`.
 318        """
 319
 320        self.searchResultsFile = "search-results.md"
 321        """Filename with all found instruments searched by part of its ticker, FIGI or name. Default: `search-results.md`.
 322
 323        See also: `SearchInstruments()`.
 324        """
 325
 326        self.pricesFile = "prices.md"
 327        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 328
 329        See also: `GetListOfPrices()`.
 330        """
 331
 332        self.infoFile = "info.md"
 333        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 334
 335        See also: `ShowInstrumentsInfo()`, `RequestBondCoupons()` and `RequestTradingStatus()`.
 336        """
 337
 338        self.bondsXLSXFile = "ext-bonds.xlsx"
 339        """Filename where wider Pandas DataFrame with more information about bonds: main info, current prices, 
 340        bonds payment calendar, some statistics will be stored. Default: `ext-bonds.xlsx`.
 341
 342        See also: `ExtendBondsData()`.
 343        """
 344
 345        self.calendarFile = "calendar.md"
 346        """Filename where bonds payment calendar will be saved. Default: `calendar.md`.
 347        
 348        Pandas dataframe with only bonds payment calendar also will be stored to default file `calendar.xlsx`.
 349
 350        See also: `CreateBondsCalendar()`, `ShowBondsCalendar()`, `ShowInstrumentInfo()`, `RequestBondCoupons()` and `ExtendBondsData()`.
 351        """
 352
 353        self.overviewFile = "overview.md"
 354        """Filename where current portfolio, open trades and orders will be saved. Default: `overview.md`.
 355
 356        See also: `Overview()`, `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders()` and `RequestStopOrders()`.
 357        """
 358
 359        self.overviewDigestFile = "overview-digest.md"
 360        """Filename where short digest of the portfolio status will be saved. Default: `overview-digest.md`.
 361
 362        See also: `Overview()` with parameter `details="digest"`.
 363        """
 364
 365        self.overviewPositionsFile = "overview-positions.md"
 366        """Filename where only open positions, without everything else will be saved. Default: `overview-positions.md`.
 367
 368        See also: `Overview()` with parameter `details="positions"`.
 369        """
 370
 371        self.overviewOrdersFile = "overview-orders.md"
 372        """Filename where open limits and stop orders will be saved. Default: `overview-orders.md`.
 373
 374        See also: `Overview()` with parameter `details="orders"`.
 375        """
 376
 377        self.overviewAnalyticsFile = "overview-analytics.md"
 378        """Filename where only the analytics section and the distribution of the portfolio by various categories will be saved. Default: `overview-analytics.md`.
 379
 380        See also: `Overview()` with parameter `details="analytics"`.
 381        """
 382
 383        self.reportFile = "deals.md"
 384        """Filename where history of deals and trade statistics will be saved. Default: `deals.md`.
 385
 386        See also: `Deals()`.
 387        """
 388
 389        self.withdrawalLimitsFile = "limits.md"
 390        """Filename where table of funds available for withdrawal will be saved. Default: `limits.md`.
 391
 392        See also: `OverviewLimits()` and `RequestLimits()`.
 393        """
 394
 395        self.userInfoFile = "user-info.md"
 396        """Filename where all available user's data (`accountId`s, common user information, margin status and tariff connections limit) will be saved. Default: `user-info.md`.
 397
 398        See also: `OverviewUserInfo()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()`.
 399        """
 400
 401        self.userAccountsFile = "accounts.md"
 402        """Filename where simple table with all available user accounts (`accountId`s) will be saved. Default: `accounts.md`.
 403
 404        See also: `OverviewAccounts()`, `RequestAccounts()`.
 405        """
 406
 407        self.iListDumpFile = "dump.json" if defaultCache is None or not isinstance(defaultCache, str) or not defaultCache else defaultCache
 408        """Filename where raw data about shares, currencies, bonds, etfs and futures will be stored. Default: `dump.json`.
 409
 410        Pandas dataframe with raw instruments data also will be stored to default file `dump.xlsx`.
 411
 412        See also: `DumpInstruments()` and `DumpInstrumentsAsXLSX()`.
 413        """
 414
 415        self.iList = None  # init iList for raw instruments data
 416        """Dictionary with raw data about shares, currencies, bonds, etfs and futures from broker server. Auto-updating and saving dump to the `iListDumpFile`.
 417        
 418        See also: `Listing()`, `DumpInstruments()`.
 419        """
 420
 421        # trying to re-load raw instruments data from file `iListDumpFile` or try to update it from server:
 422        if useCache:
 423            if os.path.exists(self.iListDumpFile):
 424                dumpTime = datetime.fromtimestamp(os.path.getmtime(self.iListDumpFile)).astimezone(tzutc())  # dump modification date and time
 425                curTime = datetime.now(tzutc())
 426
 427                if (curTime.day > dumpTime.day) or (curTime.month > dumpTime.month) or (curTime.year > dumpTime.year):
 428                    uLogger.warning("Local cache may be outdated! It has last modified [{}] UTC. Updating from broker server, wait, please...".format(dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
 429
 430                    self.DumpInstruments(forceUpdate=True)  # updating self.iList and dump file
 431
 432                else:
 433                    self.iList = json.load(open(self.iListDumpFile, mode="r", encoding="UTF-8"))  # load iList from dump
 434
 435                    uLogger.debug("Local cache with raw instruments data is used: [{}]. Last modified: [{}] UTC".format(
 436                        os.path.abspath(self.iListDumpFile),
 437                        dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT),
 438                    ))
 439
 440            else:
 441                uLogger.warning("Local cache with raw instruments data not exists! Creating new dump, wait, please...")
 442                self.DumpInstruments(forceUpdate=True)  # updating self.iList and creating default dump file
 443
 444        else:
 445            self.iList = self.Listing()  # request new raw instruments data from broker server
 446            self.DumpInstruments(forceUpdate=False)  # save raw instrument's data to default dump file `iListDumpFile`
 447
 448        self.priceModel = PriceGenerator()  # init PriceGenerator object to work with candles data
 449        """PriceGenerator object to work with candles data: load, render interact and non-interact charts and so on.
 450
 451        See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
 452        """
 453
 454    def _ParseJSON(self, rawData="{}") -> dict:
 455        """
 456        Parse JSON from response string.
 457
 458        :param rawData: this is a string with JSON-formatted text.
 459        :return: JSON (dictionary), parsed from server response string.
 460        """
 461        responseJSON = json.loads(rawData) if rawData else {}
 462
 463        if self.moreDebug:
 464            uLogger.debug("JSON formatted raw body data of response:\n{}".format(json.dumps(responseJSON, indent=4)))
 465
 466        return responseJSON
 467
 468    def SendAPIRequest(self, url: str, reqType: str = "GET", retry: int = 3, pause: int = 5) -> dict:
 469        """
 470        Send GET or POST request to broker server and receive JSON object.
 471
 472        self.header: must be defining with dictionary of headers.
 473        self.body: if define then used as request body. None by default.
 474        self.timeout: global request timeout, 15 seconds by default.
 475        :param url: url with REST request.
 476        :param reqType: send "GET" or "POST" request. "GET" by default.
 477        :param retry: how many times retry after first request if an 5xx server errors occurred.
 478        :param pause: sleep time in seconds between retries.
 479        :return: response JSON (dictionary) from broker.
 480        """
 481        if reqType not in ("GET", "POST"):
 482            uLogger.error("You can define request type: 'GET' or 'POST'!")
 483            raise Exception("Incorrect value")
 484
 485        if self.moreDebug:
 486            uLogger.debug("Request parameters:")
 487            uLogger.debug("    - REST API URL: {}".format(url))
 488            uLogger.debug("    - request type: {}".format(reqType))
 489            uLogger.debug("    - headers:\n{}".format(str(self.headers).replace(self.token, "*** request token ***")))
 490            uLogger.debug("    - body:\n{}".format(self.body))
 491
 492        # fast hack to avoid all operations with some tickers/FIGI
 493        responseJSON = {}
 494        oK = True
 495        for item in self.exclude:
 496            if item in url:
 497                if self.moreDebug:
 498                    uLogger.warning("Do not execute operations with list of this tickers/FIGI: {}".format(str(self.exclude)))
 499
 500                oK = False
 501                break
 502
 503        if oK:
 504            counter = 0
 505            response = None
 506            errMsg = ""
 507
 508            while not response and counter <= retry:
 509                if reqType == "GET":
 510                    response = requests.get(url, headers=self.headers, data=self.body, timeout=self.timeout)
 511
 512                if reqType == "POST":
 513                    response = requests.post(url, headers=self.headers, data=self.body, timeout=self.timeout)
 514
 515                if self.moreDebug:
 516                    uLogger.debug("Response:")
 517                    uLogger.debug("    - status code: {}".format(response.status_code))
 518                    uLogger.debug("    - reason: {}".format(response.reason))
 519                    uLogger.debug("    - body length: {}".format(len(response.text)))
 520                    uLogger.debug("    - headers:\n{}".format(response.headers))
 521
 522                # Server returns some headers:
 523                # - `x-ratelimit-limit` - shows the settings of the current user limit for this method.
 524                # - `x-ratelimit-remaining` - the number of remaining requests of this type per minute.
 525                # - `x-ratelimit-reset` - time in seconds before resetting the request counter.
 526                # See: https://tinkoff.github.io/investAPI/grpc/#kreya
 527                if "x-ratelimit-remaining" in response.headers.keys() and response.headers["x-ratelimit-remaining"] == "0":
 528                    rateLimitWait = int(response.headers["x-ratelimit-reset"])
 529                    uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
 530                    sleep(rateLimitWait)
 531
 532                # Error status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 533                if 400 <= response.status_code < 500:
 534                    msg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 535                    uLogger.debug("    - not oK, but do not retry for 4xx errors, {}".format(msg))
 536                    counter = retry + 1
 537
 538                if 500 <= response.status_code < 600:
 539                    errMsg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 540                    uLogger.debug("    - not oK, {}".format(errMsg))
 541                    counter += 1
 542
 543                    if counter <= retry:
 544                        uLogger.debug("Retry: [{}]. Wait {} sec. and try again...".format(counter, pause))
 545                        sleep(pause)
 546
 547            responseJSON = self._ParseJSON(rawData=response.text)
 548
 549            if errMsg:
 550                uLogger.error("Server returns not `oK` status! See: https://tinkoff.github.io/investAPI/errors/")
 551                uLogger.error("    - not oK, {}".format(errMsg))
 552
 553        return responseJSON
 554
 555    def _IUpdater(self, iType: str) -> tuple:
 556        """
 557        Request instrument by type from server. See available API methods for instruments:
 558        Currencies: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Currencies
 559        Shares: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Shares
 560        Bonds: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Bonds
 561        Etfs: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Etfs
 562        Futures: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Futures
 563
 564        :param iType: type of the instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 565        :return: tuple with iType name and list of available instruments of current type for defined user token.
 566        """
 567        result = []
 568
 569        if iType in TKS_INSTRUMENTS:
 570            uLogger.debug("Requesting available [{}] list. Wait, please...".format(iType))
 571
 572            # all instruments have the same body in API v2 requests:
 573            self.body = str({"instrumentStatus": "INSTRUMENT_STATUS_UNSPECIFIED"})  # Enum: [INSTRUMENT_STATUS_UNSPECIFIED, INSTRUMENT_STATUS_BASE, INSTRUMENT_STATUS_ALL]
 574            instrumentURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/{}".format(iType)
 575            result = self.SendAPIRequest(instrumentURL, reqType="POST")["instruments"]
 576
 577        return iType, result
 578
 579    def _IWrapper(self, kwargs):
 580        """
 581        Wrapper runs instrument's update method `_IUpdater()`.
 582        It's a workaround for using multiprocessing with kwargs. See: https://stackoverflow.com/a/36799206
 583        """
 584        return self._IUpdater(**kwargs)
 585
 586    def Listing(self) -> dict:
 587        """
 588        Gets JSON with raw data about shares, currencies, bonds, etfs and futures from broker server.
 589
 590        :return: Dictionary with all available broker instruments: currencies, shares, bonds, etfs and futures.
 591        """
 592        uLogger.debug("Requesting all available instruments for current account. Wait, please...")
 593        uLogger.debug("CPU usages for parallel requests: [{}]".format(CPU_USAGES))
 594
 595        # this parameters insert to requests: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService
 596        # iType is type of instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 597        iParams = [{"iType": iType} for iType in TKS_INSTRUMENTS]
 598
 599        poolUpdater = ThreadPool(processes=CPU_USAGES)  # create pool for update instruments in parallel mode
 600        listing = poolUpdater.map(self._IWrapper, iParams)  # execute update operations
 601        poolUpdater.close()
 602
 603        # Dictionary with all broker instruments: shares, currencies, bonds, etfs and futures.
 604        # Next in this code: item[0] is "iType" and item[1] is list of available instruments from the result of _IUpdater() method
 605        iList = {item[0]: {instrument["ticker"]: instrument for instrument in item[1]} for item in listing}
 606
 607        # calculate minimum price increment (step) for all instruments and set up instrument's type:
 608        for iType in iList.keys():
 609            for ticker in iList[iType]:
 610                iList[iType][ticker]["type"] = iType
 611
 612                if "minPriceIncrement" in iList[iType][ticker].keys():
 613                    iList[iType][ticker]["step"] = NanoToFloat(
 614                        iList[iType][ticker]["minPriceIncrement"]["units"],
 615                        iList[iType][ticker]["minPriceIncrement"]["nano"],
 616                    )
 617
 618                else:
 619                    iList[iType][ticker]["step"] = 0  # hack to avoid empty value in some instruments, e.g. futures
 620
 621        return iList
 622
 623    def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:
 624        """
 625        Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.
 626
 627        See also: `DumpInstruments()`, `Listing()`.
 628
 629        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 630                            otherwise just saves exist `iList` as XLSX-file (default: `dump.xlsx`) .
 631        """
 632        if self.iListDumpFile is None or not self.iListDumpFile:
 633            uLogger.error("Output name of dump file must be defined!")
 634            raise Exception("Filename required")
 635
 636        if not self.iList or forceUpdate:
 637            self.iList = self.Listing()
 638
 639        xlsxDumpFile = self.iListDumpFile.replace(".json", ".xlsx") if self.iListDumpFile.endswith(".json") else self.iListDumpFile + ".xlsx"
 640
 641        # Save as XLSX with separated sheets for every type of instruments:
 642        with pd.ExcelWriter(
 643                path=xlsxDumpFile,
 644                date_format=TKS_DATE_FORMAT,
 645                datetime_format=TKS_DATE_TIME_FORMAT,
 646                mode="w",
 647        ) as writer:
 648            for iType in TKS_INSTRUMENTS:
 649                df = pd.DataFrame.from_dict(data=self.iList[iType], orient="index")  # generate pandas object from self.iList dictionary
 650                df = df[sorted(df)]  # sorted by column names
 651                df = df.applymap(
 652                    lambda item: NanoToFloat(item["units"], item["nano"]) if isinstance(item, dict) and "units" in item.keys() and "nano" in item.keys() else item,
 653                    na_action="ignore",
 654                )  # converting numbers from nano-type to float in every cell
 655                df.to_excel(
 656                    writer,
 657                    sheet_name=iType,
 658                    encoding="UTF-8",
 659                    freeze_panes=(1, 1),
 660                )  # saving as XLSX-file with freeze first row and column as headers
 661
 662        uLogger.info("XLSX-file for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxDumpFile)))
 663
 664    def DumpInstruments(self, forceUpdate: bool = True) -> str:
 665        """
 666        Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server
 667        using `Listing()` method. If `iListDumpFile` string is not empty then also save information to this file.
 668
 669        See also: `DumpInstrumentsAsXLSX()`, `Listing()`.
 670
 671        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 672                            otherwise just saves exist `iList` as JSON-file (default: `dump.json`).
 673        :return: serialized JSON formatted `str` with full data of instruments, also saved to the `--output` JSON-file.
 674        """
 675        if self.iListDumpFile is None or not self.iListDumpFile:
 676            uLogger.error("Output name of dump file must be defined!")
 677            raise Exception("Filename required")
 678
 679        if not self.iList or forceUpdate:
 680            self.iList = self.Listing()
 681
 682        jsonDump = json.dumps(self.iList, indent=4, sort_keys=False)  # create JSON object as string
 683        with open(self.iListDumpFile, mode="w", encoding="UTF-8") as fH:
 684            fH.write(jsonDump)
 685
 686        uLogger.info("New cache of instruments data was created: [{}]".format(os.path.abspath(self.iListDumpFile)))
 687
 688        return jsonDump
 689
 690    def ShowInstrumentInfo(self, iJSON: dict, show: bool = True) -> str:
 691        """
 692        Show information about one instrument defined by json data and prints it in Markdown format.
 693
 694        See also: `SearchByTicker()`, `SearchByFIGI()`, `RequestBondCoupons()`, `ExtendBondsData()`, `ShowBondsCalendar()` and `RequestTradingStatus()`.
 695
 696        :param iJSON: json data of instrument, example: `iJSON = self.iList["Shares"][self.ticker]`
 697        :param show: if `True` then also printing information about instrument and its current price.
 698        :return: multilines text in Markdown format with information about one instrument.
 699        """
 700        splitLine = "|                                                             |                                                        |\n"
 701        infoText = ""
 702
 703        if iJSON is not None and iJSON and isinstance(iJSON, dict):
 704            info = [
 705                "# Main information: ticker [{}], FIGI [{}]\n\n".format(iJSON["ticker"], iJSON["figi"]),
 706                "* Actual at: [{}] (UTC)\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
 707                "| Parameters                                                  | Values                                                 |\n",
 708                "|-------------------------------------------------------------|--------------------------------------------------------|\n",
 709                "| Ticker:                                                     | {:<54} |\n".format(iJSON["ticker"]),
 710                "| Full name:                                                  | {:<54} |\n".format(iJSON["name"]),
 711            ]
 712
 713            if "sector" in iJSON.keys() and iJSON["sector"]:
 714                info.append("| Sector:                                                     | {:<54} |\n".format(iJSON["sector"]))
 715
 716            info.append("| Country of instrument:                                      | {:<54} |\n".format("{}{}".format(
 717                "({}) ".format(iJSON["countryOfRisk"]) if "countryOfRisk" in iJSON.keys() and iJSON["countryOfRisk"] else "",
 718                iJSON["countryOfRiskName"] if "countryOfRiskName" in iJSON.keys() and iJSON["countryOfRiskName"] else "",
 719            )))
 720
 721            info.extend([
 722                splitLine,
 723                "| FIGI (Financial Instrument Global Identifier):              | {:<54} |\n".format(iJSON["figi"]),
 724                "| Exchange:                                                   | {:<54} |\n".format(iJSON["exchange"]),
 725            ])
 726
 727            if "isin" in iJSON.keys() and iJSON["isin"]:
 728                info.append("| ISIN (International Securities Identification Number):      | {:<54} |\n".format(iJSON["isin"]))
 729
 730            if "classCode" in iJSON.keys():
 731                info.append("| Class Code (exchange section where instrument is traded):   | {:<54} |\n".format(iJSON["classCode"]))
 732
 733            info.extend([
 734                splitLine,
 735                "| Current broker security trading status:                     | {:<54} |\n".format(TKS_TRADING_STATUSES[iJSON["tradingStatus"]]),
 736                splitLine,
 737                "| Buy operations allowed:                                     | {:<54} |\n".format("Yes" if iJSON["buyAvailableFlag"] else "No"),
 738                "| Sale operations allowed:                                    | {:<54} |\n".format("Yes" if iJSON["sellAvailableFlag"] else "No"),
 739                "| Short positions allowed:                                    | {:<54} |\n".format("Yes" if iJSON["shortEnabledFlag"] else "No"),
 740            ])
 741
 742            if iJSON["figi"]:
 743                self.figi = iJSON["figi"]
 744                iJSON = iJSON | self.RequestTradingStatus()
 745
 746                info.extend([
 747                    splitLine,
 748                    "| Limit orders allowed:                                       | {:<54} |\n".format("Yes" if iJSON["limitOrderAvailableFlag"] else "No"),
 749                    "| Market orders allowed:                                      | {:<54} |\n".format("Yes" if iJSON["marketOrderAvailableFlag"] else "No"),
 750                    "| API trade allowed:                                          | {:<54} |\n".format("Yes" if iJSON["apiTradeAvailableFlag"] else "No"),
 751                ])
 752
 753            info.append(splitLine)
 754
 755            if "type" in iJSON.keys() and iJSON["type"]:
 756                info.append("| Type of the instrument:                                     | {:<54} |\n".format(iJSON["type"]))
 757
 758            if "futuresType" in iJSON.keys() and iJSON["futuresType"]:
 759                info.append("| Futures type:                                               | {:<54} |\n".format(iJSON["futuresType"]))
 760
 761            if "ipoDate" in iJSON.keys() and iJSON["ipoDate"]:
 762                info.append("| IPO date:                                                   | {:<54} |\n".format(iJSON["ipoDate"].replace("T", " ").replace("Z", "")))
 763
 764            if "releasedDate" in iJSON.keys() and iJSON["releasedDate"]:
 765                info.append("| Released date:                                              | {:<54} |\n".format(iJSON["releasedDate"].replace("T", " ").replace("Z", "")))
 766
 767            if "rebalancingFreq" in iJSON.keys() and iJSON["rebalancingFreq"]:
 768                info.append("| Rebalancing frequency:                                      | {:<54} |\n".format(iJSON["rebalancingFreq"]))
 769
 770            if "focusType" in iJSON.keys() and iJSON["focusType"]:
 771                info.append("| Focusing type:                                              | {:<54} |\n".format(iJSON["focusType"]))
 772
 773            if "assetType" in iJSON.keys() and iJSON["assetType"]:
 774                info.append("| Asset type:                                                 | {:<54} |\n".format(iJSON["assetType"]))
 775
 776            if "basicAsset" in iJSON.keys() and iJSON["basicAsset"]:
 777                info.append("| Basic asset:                                                | {:<54} |\n".format(iJSON["basicAsset"]))
 778
 779            if "basicAssetSize" in iJSON.keys() and iJSON["basicAssetSize"]:
 780                info.append("| Basic asset size:                                           | {:<54} |\n".format("{:.2f}".format(NanoToFloat(str(iJSON["basicAssetSize"]["units"]), iJSON["basicAssetSize"]["nano"]))))
 781
 782            if "isoCurrencyName" in iJSON.keys() and iJSON["isoCurrencyName"]:
 783                info.append("| ISO currency name:                                          | {:<54} |\n".format(iJSON["isoCurrencyName"]))
 784
 785            if "currency" in iJSON.keys():
 786                info.append("| Payment currency:                                           | {:<54} |\n".format(iJSON["currency"]))
 787
 788            if iJSON["type"] == "Bonds" and "nominal" in iJSON.keys() and "currency" in iJSON["nominal"].keys():
 789                info.append("| Nominal currency:                                           | {:<54} |\n".format(iJSON["nominal"]["currency"]))
 790
 791            if "firstTradeDate" in iJSON.keys() and iJSON["firstTradeDate"]:
 792                info.append("| First trade date:                                           | {:<54} |\n".format(iJSON["firstTradeDate"].replace("T", " ").replace("Z", "")))
 793
 794            if "lastTradeDate" in iJSON.keys() and iJSON["lastTradeDate"]:
 795                info.append("| Last trade date:                                            | {:<54} |\n".format(iJSON["lastTradeDate"].replace("T", " ").replace("Z", "")))
 796
 797            if "expirationDate" in iJSON.keys() and iJSON["expirationDate"]:
 798                info.append("| Date of expiration:                                         | {:<54} |\n".format(iJSON["expirationDate"].replace("T", " ").replace("Z", "")))
 799
 800            if "stateRegDate" in iJSON.keys() and iJSON["stateRegDate"]:
 801                info.append("| State registration date:                                    | {:<54} |\n".format(iJSON["stateRegDate"].replace("T", " ").replace("Z", "")))
 802
 803            if "placementDate" in iJSON.keys() and iJSON["placementDate"]:
 804                info.append("| Placement date:                                             | {:<54} |\n".format(iJSON["placementDate"].replace("T", " ").replace("Z", "")))
 805
 806            if "maturityDate" in iJSON.keys() and iJSON["maturityDate"]:
 807                info.append("| Maturity date:                                              | {:<54} |\n".format(iJSON["maturityDate"].replace("T", " ").replace("Z", "")))
 808
 809            if "perpetualFlag" in iJSON.keys() and iJSON["perpetualFlag"]:
 810                info.append("| Perpetual bond:                                             | Yes                                                    |\n")
 811
 812            if "otcFlag" in iJSON.keys() and iJSON["otcFlag"]:
 813                info.append("| Over-the-counter (OTC) securities:                          | Yes                                                    |\n")
 814
 815            iExt = None
 816            if iJSON["type"] == "Bonds":
 817                info.extend([
 818                    splitLine,
 819                    "| Bond issue (size / plan):                                   | {:<54} |\n".format("{} / {}".format(iJSON["issueSize"], iJSON["issueSizePlan"])),
 820                    "| Nominal price (100%):                                       | {:<54} |\n".format("{} {}".format(
 821                        "{:.2f}".format(NanoToFloat(str(iJSON["nominal"]["units"]), iJSON["nominal"]["nano"])).rstrip("0").rstrip("."),
 822                        iJSON["nominal"]["currency"],
 823                    )),
 824                ])
 825
 826                if "floatingCouponFlag" in iJSON.keys():
 827                    info.append("| Floating coupon:                                            | {:<54} |\n".format("Yes" if iJSON["floatingCouponFlag"] else "No"))
 828
 829                if "amortizationFlag" in iJSON.keys():
 830                    info.append("| Amortization:                                               | {:<54} |\n".format("Yes" if iJSON["amortizationFlag"] else "No"))
 831
 832                info.append(splitLine)
 833
 834                if "couponQuantityPerYear" in iJSON.keys() and iJSON["couponQuantityPerYear"]:
 835                    info.append("| Number of coupon payments per year:                         | {:<54} |\n".format(iJSON["couponQuantityPerYear"]))
 836
 837                if iJSON["figi"]:
 838                    iExt = self.ExtendBondsData(instruments=iJSON["figi"], xlsx=False)  # extended bonds data
 839
 840                    info.extend([
 841                        "| Days last to maturity date:                                 | {:<54} |\n".format(iExt["daysToMaturity"][0]),
 842                        "| Coupons yield (average coupon daily yield * 365):           | {:<54} |\n".format("{:.2f}%".format(iExt["couponsYield"][0])),
 843                        "| Current price yield (average daily yield * 365):            | {:<54} |\n".format("{:.2f}%".format(iExt["currentYield"][0])),
 844                    ])
 845
 846                if "aciValue" in iJSON.keys() and iJSON["aciValue"]:
 847                    info.append("| Current accumulated coupon income (ACI):                    | {:<54} |\n".format("{:.2f} {}".format(
 848                        NanoToFloat(str(iJSON["aciValue"]["units"]), iJSON["aciValue"]["nano"]),
 849                        iJSON["aciValue"]["currency"]
 850                    )))
 851
 852            if "currentPrice" in iJSON.keys():
 853                info.append(splitLine)
 854
 855                currency = iJSON["currency"] if "currency" in iJSON.keys() else ""  # nominal currency for bonds, otherwise currency of instrument
 856                aciCurrency = iExt["aciCurrency"][0] if iJSON["type"] == "Bonds" and iExt is not None and "aciCurrency" in iExt.keys() else ""  # payment currency
 857
 858                bondPrevClose = iExt["closePrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "closePrice" in iExt.keys() else 0  # previous close price of bond
 859                bondLastPrice = iExt["lastPrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "lastPrice" in iExt.keys() else 0  # last price of bond
 860                bondLimitUp = iExt["limitUp"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitUp" in iExt.keys() else 0  # max price of bond
 861                bondLimitDown = iExt["limitDown"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitDown" in iExt.keys() else 0  # min price of bond
 862                bondChangesDelta = iExt["changesDelta"][0] if iJSON["type"] == "Bonds" and iExt is not None and "changesDelta" in iExt.keys() else 0  # delta between last deal price and last close
 863
 864                curPriceSell = iJSON["currentPrice"]["sell"][0]["price"] if iJSON["currentPrice"]["sell"] else 0
 865                curPriceBuy = iJSON["currentPrice"]["buy"][0]["price"] if iJSON["currentPrice"]["buy"] else 0
 866
 867                info.extend([
 868                    "| Previous close price of the instrument:                     | {:<54} |\n".format("{}{}".format(
 869                        "{}".format(iJSON["currentPrice"]["closePrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["closePrice"] is not None else "N/A",
 870                        "% of nominal price ({:.2f} {})".format(bondPrevClose, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 871                    )),
 872                    "| Last deal price of the instrument:                          | {:<54} |\n".format("{}{}".format(
 873                        "{}".format(iJSON["currentPrice"]["lastPrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["lastPrice"] is not None else "N/A",
 874                        "% of nominal price ({:.2f} {})".format(bondLastPrice, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 875                    )),
 876                    "| Changes between last deal price and last close              | {:<54} |\n".format(
 877                        "{:.2f}%{}".format(
 878                            iJSON["currentPrice"]["changes"],
 879                            " ({}{:.2f} {})".format(
 880                                "+" if bondChangesDelta > 0 else "",
 881                                bondChangesDelta,
 882                                aciCurrency
 883                            ) if iJSON["type"] == "Bonds" else " ({}{:.2f} {})".format(
 884                                "+" if iJSON["currentPrice"]["lastPrice"] > iJSON["currentPrice"]["closePrice"] else "",
 885                                iJSON["currentPrice"]["lastPrice"] - iJSON["currentPrice"]["closePrice"],
 886                                currency
 887                            ),
 888                        )
 889                    ),
 890                    "| Current limit price, min / max:                             | {:<54} |\n".format("{}{} / {}{}{}".format(
 891                        "{}".format(iJSON["currentPrice"]["limitDown"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitDown"] is not None else "N/A",
 892                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 893                        "{}".format(iJSON["currentPrice"]["limitUp"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitUp"] is not None else "N/A",
 894                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 895                        " ({:.2f} {} / {:.2f} {})".format(bondLimitDown, aciCurrency, bondLimitUp, aciCurrency) if iJSON["type"] == "Bonds" else ""
 896                    )),
 897                    "| Actual price, sell / buy:                                   | {:<54} |\n".format("{}{} / {}{}{}".format(
 898                        "{}".format(curPriceSell).rstrip("0").rstrip(".") if curPriceSell != 0 else "N/A",
 899                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 900                        "{}".format(curPriceBuy).rstrip("0").rstrip(".") if curPriceBuy != 0 else "N/A",
 901                        "%" if iJSON["type"] == "Bonds" else" {}".format(currency),
 902                        " ({:.2f} {} / {:.2f} {})".format(curPriceSell, aciCurrency, curPriceBuy, aciCurrency) if iJSON["type"] == "Bonds" else ""
 903                    )),
 904                ])
 905
 906            if "lot" in iJSON.keys():
 907                info.append("| Minimum lot to buy:                                         | {:<54} |\n".format(iJSON["lot"]))
 908
 909            if "step" in iJSON.keys() and iJSON["step"] != 0:
 910                info.append("| Minimum price increment (step):                             | {:<54} |\n".format(iJSON["step"]))
 911
 912            # Add bond payment calendar:
 913            if iJSON["type"] == "Bonds":
 914                strCalendar = self.ShowBondsCalendar(extBonds=iExt, show=False)   # bond payment calendar
 915                info.extend(["\n", strCalendar])
 916
 917            infoText += "".join(info)
 918
 919            if show:
 920                uLogger.info("{}".format(infoText))
 921
 922            else:
 923                uLogger.debug("{}".format(infoText))
 924
 925            if self.infoFile is not None:
 926                with open(self.infoFile, "w", encoding="UTF-8") as fH:
 927                    fH.write(infoText)
 928
 929                uLogger.info("Info about instrument with ticker [{}] and FIGI [{}] was saved to file: [{}]".format(iJSON["ticker"], iJSON["figi"], os.path.abspath(self.infoFile)))
 930
 931        return infoText
 932
 933    def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:
 934        """
 935        Search and return raw broker's information about instrument by its ticker. Variable `ticker` must be defined!
 936
 937        :param requestPrice: if `False` then do not request current price of instrument (because this is long operation).
 938        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 939        :return: JSON formatted data with information about instrument.
 940        """
 941        tickerJSON = {}
 942        if self.moreDebug:
 943            uLogger.debug("Searching information about instrument by it's ticker [{}] ...".format(self.ticker))
 944
 945        if not self.ticker:
 946            uLogger.warning("self.ticker variable is not be empty!")
 947
 948        else:
 949            if self.ticker in TKS_TICKERS_OR_FIGI_EXCLUDED:
 950                uLogger.warning("Instrument with ticker [{}] not allowed for trading!".format(self.ticker))
 951                raise Exception("Instrument not allowed")
 952
 953            if not self.iList:
 954                self.iList = self.Listing()
 955
 956            if self.ticker in self.iList["Shares"].keys():
 957                tickerJSON = self.iList["Shares"][self.ticker]
 958                if self.moreDebug:
 959                    uLogger.debug("Ticker [{}] found in shares list".format(self.ticker))
 960
 961            elif self.ticker in self.iList["Currencies"].keys():
 962                tickerJSON = self.iList["Currencies"][self.ticker]
 963                if self.moreDebug:
 964                    uLogger.debug("Ticker [{}] found in currencies list".format(self.ticker))
 965
 966            elif self.ticker in self.iList["Bonds"].keys():
 967                tickerJSON = self.iList["Bonds"][self.ticker]
 968                if self.moreDebug:
 969                    uLogger.debug("Ticker [{}] found in bonds list".format(self.ticker))
 970
 971            elif self.ticker in self.iList["Etfs"].keys():
 972                tickerJSON = self.iList["Etfs"][self.ticker]
 973                if self.moreDebug:
 974                    uLogger.debug("Ticker [{}] found in etfs list".format(self.ticker))
 975
 976            elif self.ticker in self.iList["Futures"].keys():
 977                tickerJSON = self.iList["Futures"][self.ticker]
 978                if self.moreDebug:
 979                    uLogger.debug("Ticker [{}] found in futures list".format(self.ticker))
 980
 981        if tickerJSON:
 982            self.figi = tickerJSON["figi"]
 983
 984            if requestPrice:
 985                tickerJSON["currentPrice"] = self.GetCurrentPrices(show=False)
 986
 987                if tickerJSON["currentPrice"]["closePrice"] is not None and tickerJSON["currentPrice"]["closePrice"] != 0 and tickerJSON["currentPrice"]["lastPrice"] is not None:
 988                    tickerJSON["currentPrice"]["changes"] = 100 * (tickerJSON["currentPrice"]["lastPrice"] - tickerJSON["currentPrice"]["closePrice"]) / tickerJSON["currentPrice"]["closePrice"]
 989
 990                else:
 991                    tickerJSON["currentPrice"]["changes"] = 0
 992
 993            if show:
 994                self.ShowInstrumentInfo(iJSON=tickerJSON, show=True)  # print info as Markdown text
 995
 996        else:
 997            if show:
 998                uLogger.warning("Ticker [{}] not found in available broker instrument's list!".format(self.ticker))
 999
1000        return tickerJSON
1001
1002    def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:
1003        """
1004        Search and return raw broker's information about instrument by its FIGI. Variable `figi` must be defined!
1005
1006        :param requestPrice: if `False` then do not request current price of instrument (it's long operation).
1007        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
1008        :return: JSON formatted data with information about instrument.
1009        """
1010        figiJSON = {}
1011        if self.moreDebug:
1012            uLogger.debug("Searching information about instrument by it's FIGI [{}] ...".format(self.figi))
1013
1014        if not self.figi:
1015            uLogger.warning("self.figi variable is not be empty!")
1016
1017        else:
1018            if self.figi in TKS_TICKERS_OR_FIGI_EXCLUDED:
1019                uLogger.warning("Instrument with figi [{}] not allowed for trading!".format(self.figi))
1020                raise Exception("Instrument not allowed")
1021
1022            if not self.iList:
1023                self.iList = self.Listing()
1024
1025            for item in self.iList["Shares"].keys():
1026                if self.figi == self.iList["Shares"][item]["figi"]:
1027                    figiJSON = self.iList["Shares"][item]
1028
1029                    if self.moreDebug:
1030                        uLogger.debug("FIGI [{}] found in shares list".format(self.figi))
1031
1032                    break
1033
1034            if not figiJSON:
1035                for item in self.iList["Currencies"].keys():
1036                    if self.figi == self.iList["Currencies"][item]["figi"]:
1037                        figiJSON = self.iList["Currencies"][item]
1038
1039                        if self.moreDebug:
1040                            uLogger.debug("FIGI [{}] found in currencies list".format(self.figi))
1041
1042                        break
1043
1044            if not figiJSON:
1045                for item in self.iList["Bonds"].keys():
1046                    if self.figi == self.iList["Bonds"][item]["figi"]:
1047                        figiJSON = self.iList["Bonds"][item]
1048
1049                        if self.moreDebug:
1050                            uLogger.debug("FIGI [{}] found in bonds list".format(self.figi))
1051
1052                        break
1053
1054            if not figiJSON:
1055                for item in self.iList["Etfs"].keys():
1056                    if self.figi == self.iList["Etfs"][item]["figi"]:
1057                        figiJSON = self.iList["Etfs"][item]
1058
1059                        if self.moreDebug:
1060                            uLogger.debug("FIGI [{}] found in etfs list".format(self.figi))
1061
1062                        break
1063
1064            if not figiJSON:
1065                for item in self.iList["Futures"].keys():
1066                    if self.figi == self.iList["Futures"][item]["figi"]:
1067                        figiJSON = self.iList["Futures"][item]
1068
1069                        if self.moreDebug:
1070                            uLogger.debug("FIGI [{}] found in futures list".format(self.figi))
1071
1072                        break
1073
1074        if figiJSON:
1075            self.figi = figiJSON["figi"]
1076            self.ticker = figiJSON["ticker"]
1077
1078            if requestPrice:
1079                figiJSON["currentPrice"] = self.GetCurrentPrices(show=False)
1080
1081                if figiJSON["currentPrice"]["closePrice"] is not None and figiJSON["currentPrice"]["closePrice"] != 0 and figiJSON["currentPrice"]["lastPrice"] is not None:
1082                    figiJSON["currentPrice"]["changes"] = 100 * (figiJSON["currentPrice"]["lastPrice"] - figiJSON["currentPrice"]["closePrice"]) / figiJSON["currentPrice"]["closePrice"]
1083
1084                else:
1085                    figiJSON["currentPrice"]["changes"] = 0
1086
1087            if show:
1088                self.ShowInstrumentInfo(iJSON=figiJSON, show=True)  # print info as Markdown text
1089
1090        else:
1091            if show:
1092                uLogger.warning("FIGI [{}] not found in available broker instrument's list!".format(self.figi))
1093
1094        return figiJSON
1095
1096    def GetCurrentPrices(self, show: bool = True) -> dict:
1097        """
1098        Get and show Depth of Market with current prices of the instrument as dictionary. Result example with `depth` 5:
1099        `{"buy": [{"price": 1243.8, "quantity": 193},
1100                  {"price": 1244.0, "quantity": 168},
1101                  {"price": 1244.8, "quantity": 5},
1102                  {"price": 1245.0, "quantity": 61},
1103                  {"price": 1245.4, "quantity": 60}],
1104          "sell": [{"price": 1243.6, "quantity": 8},
1105                   {"price": 1242.6, "quantity": 10},
1106                   {"price": 1242.4, "quantity": 18},
1107                   {"price": 1242.2, "quantity": 50},
1108                   {"price": 1242.0, "quantity": 113}],
1109          "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}`, where parameters mean:
1110        - buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
1111        - sell: list of dicts with Buyers prices,
1112            - price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
1113            - quantity: volume value by current price in lots,
1114        - limitUp: current trade session limit price, maximum,
1115        - limitDown: current trade session limit price, minimum,
1116        - lastPrice: last deal price of the instrument,
1117        - closePrice: previous trade session close price of the instrument.
1118
1119        See also: `SearchByTicker()` and `SearchByFIGI()`.
1120        REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1121        Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1122
1123        :param show: if `True` then print DOM to log and console.
1124        :return: orders book dict with lists of current buy and sell prices: `{"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}`.
1125                 If an error occurred then returns an empty record:
1126                 `{"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}`.
1127        """
1128        prices = {"buy": [], "sell": [], "limitUp": 0, "limitDown": 0, "lastPrice": 0, "closePrice": 0}
1129
1130        if self.depth < 1:
1131            uLogger.error("Depth of Market (DOM) must be >=1!")
1132            raise Exception("Incorrect value")
1133
1134        if not (self.ticker or self.figi):
1135            uLogger.error("self.ticker or self.figi variables must be defined!")
1136            raise Exception("Ticker or FIGI required")
1137
1138        if self.ticker and not self.figi:
1139            instrumentByTicker = self.SearchByTicker(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1140            self.figi = instrumentByTicker["figi"] if instrumentByTicker else ""
1141
1142        if not self.ticker and self.figi:
1143            instrumentByFigi = self.SearchByFIGI(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1144            self.ticker = instrumentByFigi["ticker"] if instrumentByFigi else ""
1145
1146        if not self.figi:
1147            uLogger.error("FIGI is not defined!")
1148            raise Exception("Ticker or FIGI required")
1149
1150        else:
1151            uLogger.debug("Requesting current prices: ticker [{}], FIGI [{}]. Wait, please...".format(self.ticker, self.figi))
1152
1153            # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1154            priceURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetOrderBook"
1155            self.body = str({"figi": self.figi, "depth": self.depth})
1156            pricesResponse = self.SendAPIRequest(priceURL, reqType="POST")  # Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1157
1158            if pricesResponse and not ("code" in pricesResponse.keys() or "message" in pricesResponse.keys() or "description" in pricesResponse.keys()):
1159                # list of dicts with sellers orders:
1160                prices["buy"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["asks"]]
1161
1162                # list of dicts with buyers orders:
1163                prices["sell"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["bids"]]
1164
1165                # max price of instrument at this time:
1166                prices["limitUp"] = round(NanoToFloat(pricesResponse["limitUp"]["units"], pricesResponse["limitUp"]["nano"]), 6) if "limitUp" in pricesResponse.keys() else None
1167
1168                # min price of instrument at this time:
1169                prices["limitDown"] = round(NanoToFloat(pricesResponse["limitDown"]["units"], pricesResponse["limitDown"]["nano"]), 6) if "limitDown" in pricesResponse.keys() else None
1170
1171                # last price of deal with instrument:
1172                prices["lastPrice"] = round(NanoToFloat(pricesResponse["lastPrice"]["units"], pricesResponse["lastPrice"]["nano"]), 6) if "lastPrice" in pricesResponse.keys() else 0
1173
1174                # last close price of instrument:
1175                prices["closePrice"] = round(NanoToFloat(pricesResponse["closePrice"]["units"], pricesResponse["closePrice"]["nano"]), 6) if "closePrice" in pricesResponse.keys() else 0
1176
1177            else:
1178                uLogger.warning("Server return an empty or error response! See full log. Instrument: ticker [{}], FIGI [{}]".format(self.ticker, self.figi))
1179                uLogger.debug("Server response: {}".format(pricesResponse))
1180
1181            if show:
1182                if prices["buy"] or prices["sell"]:
1183                    info = [
1184                        "Orders book actual at [{}] (UTC)\nTicker: [{}], FIGI: [{}], Depth of Market: [{}]\n".format(
1185                            datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
1186                            self.ticker,
1187                            self.figi,
1188                            self.depth,
1189                        ),
1190                        "-" * 60, "\n",
1191                        "             Orders of Buyers | Orders of Sellers\n",
1192                        "-" * 60, "\n",
1193                        "        Sell prices (volumes) | Buy prices (volumes)\n",
1194                        "-" * 60, "\n",
1195                    ]
1196
1197                    if not prices["buy"]:
1198                        info.append("                              | No orders!\n")
1199                        sumBuy = 0
1200
1201                    else:
1202                        sumBuy = sum([x["quantity"] for x in prices["buy"]])
1203                        maxMinSorted = sorted(prices["buy"], key=lambda k: k["price"], reverse=True)
1204                        for item in maxMinSorted:
1205                            info.append("                              | {} ({})\n".format(item["price"], item["quantity"]))
1206
1207                    if not prices["sell"]:
1208                        info.append("No orders!                    |\n")
1209                        sumSell = 0
1210
1211                    else:
1212                        sumSell = sum([x["quantity"] for x in prices["sell"]])
1213                        for item in prices["sell"]:
1214                            info.append("{:>29} |\n".format("{} ({})".format(item["price"], item["quantity"])))
1215
1216                    info.extend([
1217                        "-" * 60, "\n",
1218                        "{:>29} | {}\n".format("Total sell: {}".format(sumSell), "Total buy: {}".format(sumBuy)),
1219                        "-" * 60, "\n",
1220                    ])
1221
1222                    infoText = "".join(info)
1223
1224                    uLogger.info("Current prices in order book:\n\n{}".format(infoText))
1225
1226                else:
1227                    uLogger.warning("Orders book is empty at this time! Instrument: ticker [{}], FIGI [{}]".format(self.ticker, self.figi))
1228
1229        return prices
1230
1231    def ShowInstrumentsInfo(self, show: bool = True) -> str:
1232        """
1233        This method get and show information about all available broker instruments for current user account.
1234        If `instrumentsFile` string is not empty then also save information to this file.
1235
1236        :param show: if `True` then print results to console, if `False` - print only to file.
1237        :return: multi-lines string with all available broker instruments
1238        """
1239        if not self.iList:
1240            self.iList = self.Listing()
1241
1242        info = [
1243            "# All available instruments from Tinkoff Broker server for current user token\n\n",
1244            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1245        ]
1246
1247        # add instruments count by type:
1248        for iType in self.iList.keys():
1249            info.append("* **{}:** [{}]\n".format(iType, len(self.iList[iType])))
1250
1251        headerLine = "| Ticker       | Full name                                                 | FIGI         | Cur | Lot     | Step       |\n"
1252        splitLine = "|--------------|-----------------------------------------------------------|--------------|-----|---------|------------|\n"
1253
1254        # generating info tables with all instruments by type:
1255        for iType in self.iList.keys():
1256            info.extend(["\n\n## {} available. Total: [{}]\n\n".format(iType, len(self.iList[iType])), headerLine, splitLine])
1257
1258            for instrument in self.iList[iType].keys():
1259                iName = self.iList[iType][instrument]["name"]  # instrument's name
1260                if len(iName) > 57:
1261                    iName = "{}...".format(iName[:54])  # right trim for a long string
1262
1263                info.append("| {:<12} | {:<57} | {:<12} | {:<3} | {:<7} | {:<10} |\n".format(
1264                    self.iList[iType][instrument]["ticker"],
1265                    iName,
1266                    self.iList[iType][instrument]["figi"],
1267                    self.iList[iType][instrument]["currency"],
1268                    self.iList[iType][instrument]["lot"],
1269                    "{:.10f}".format(self.iList[iType][instrument]["step"]).rstrip("0").rstrip(".") if self.iList[iType][instrument]["step"] > 0 else 0,
1270                ))
1271
1272        infoText = "".join(info)
1273
1274        if show:
1275            uLogger.info(infoText)
1276
1277        if self.instrumentsFile:
1278            with open(self.instrumentsFile, "w", encoding="UTF-8") as fH:
1279                fH.write(infoText)
1280
1281            uLogger.info("All available instruments are saved to file: [{}]".format(os.path.abspath(self.instrumentsFile)))
1282
1283        return infoText
1284
1285    def SearchInstruments(self, pattern: str, show: bool = True) -> dict:
1286        """
1287        This method search and show information about instruments by part of its ticker, FIGI or name.
1288        If `searchResultsFile` string is not empty then also save information to this file.
1289
1290        :param pattern: string with part of ticker, FIGI or instrument's name.
1291        :param show: if `True` then print results to console, if `False` - return list of result only.
1292        :return: list of dictionaries with all found instruments.
1293        """
1294        if not self.iList:
1295            self.iList = self.Listing()
1296
1297        searchResults = {iType: {} for iType in self.iList}  # same as iList but will contains only filtered instruments
1298        compiledPattern = re.compile(pattern, re.IGNORECASE)
1299
1300        for iType in self.iList:
1301            for instrument in self.iList[iType].values():
1302                searchResult = compiledPattern.search(" ".join(
1303                    [instrument["ticker"], instrument["figi"], instrument["name"]]
1304                ))
1305
1306                if searchResult:
1307                    searchResults[iType][instrument["ticker"]] = instrument
1308
1309        resultsLen = sum([len(searchResults[iType]) for iType in searchResults])
1310        info = [
1311            "# Search results\n\n",
1312            "* **Search pattern:** [{}]\n".format(pattern),
1313            "* **Found instruments:** [{}]\n\n".format(resultsLen),
1314            "**Note:** you can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t TICKER --info` or `tksbrokerapi -f FIGI --info`.\n"
1315        ]
1316        infoShort = info[:]
1317
1318        headerLine = "| Type       | Ticker       | Full name                                                      | FIGI         |\n"
1319        splitLine = "|------------|--------------|----------------------------------------------------------------|--------------|\n"
1320        skippedLine = "| ...        | ...          | ...                                                            | ...          |\n"
1321
1322        if resultsLen == 0:
1323            info.append("\nNo results\n")
1324            infoShort.append("\nNo results\n")
1325            uLogger.warning("No results. Try changing your search pattern.")
1326
1327        else:
1328            for iType in searchResults:
1329                iTypeValuesCount = len(searchResults[iType].values())
1330                if iTypeValuesCount > 0:
1331                    info.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1332                    infoShort.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1333
1334                    for instrument in searchResults[iType].values():
1335                        info.append("| {:<10} | {:<12} | {:<63}| {:<13}|\n".format(
1336                            instrument["type"],
1337                            instrument["ticker"],
1338                            "{}...".format(instrument["name"][:60]) if len(instrument["name"]) > 63 else instrument["name"],  # right trim for a long string
1339                            instrument["figi"],
1340                        ))
1341
1342                    if iTypeValuesCount <= 5:
1343                        infoShort.extend(info[-iTypeValuesCount:])
1344
1345                    else:
1346                        infoShort.extend(info[-5:])
1347                        infoShort.append(skippedLine)
1348
1349        infoText = "".join(info)
1350        infoTextShort = "".join(infoShort)
1351
1352        if show:
1353            uLogger.info(infoTextShort)
1354            uLogger.info("You can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t IBM --info` or `tksbrokerapi -f BBG000BLNNH6 --info`")
1355
1356        if self.searchResultsFile:
1357            with open(self.searchResultsFile, "w", encoding="UTF-8") as fH:
1358                fH.write(infoText)
1359
1360            uLogger.info("Full search results were saved to file: [{}]".format(os.path.abspath(self.searchResultsFile)))
1361
1362        return searchResults
1363
1364    def GetUniqueFIGIs(self, instruments: list[str]) -> list:
1365        """
1366        Creating list with unique instrument FIGIs from input list of tickers or FIGIs.
1367
1368        :param instruments: list of strings with tickers or FIGIs.
1369        :return: list with unique instrument FIGIs only.
1370        """
1371        requestedInstruments = []
1372        for iName in instruments:
1373            if iName not in self.aliases.keys():
1374                if iName not in requestedInstruments:
1375                    requestedInstruments.append(iName)
1376
1377            else:
1378                if iName not in requestedInstruments:
1379                    if self.aliases[iName] not in requestedInstruments:
1380                        requestedInstruments.append(self.aliases[iName])
1381
1382        uLogger.debug("Requested instruments without duplicates of tickers or FIGIs: {}".format(requestedInstruments))
1383
1384        onlyUniqueFIGIs = []
1385        for iName in requestedInstruments:
1386            if iName in TKS_TICKERS_OR_FIGI_EXCLUDED:
1387                continue
1388
1389            self.ticker = iName
1390            iData = self.SearchByTicker(requestPrice=False)  # trying to find instrument by ticker
1391
1392            if not iData:
1393                self.ticker = ""
1394                self.figi = iName
1395
1396                iData = self.SearchByFIGI(requestPrice=False)  # trying to find instrument by FIGI
1397
1398                if not iData:
1399                    self.figi = ""
1400                    uLogger.warning("Instrument [{}] not in list of available instruments for current token!".format(iName))
1401
1402            if iData and iData["figi"] not in onlyUniqueFIGIs:
1403                onlyUniqueFIGIs.append(iData["figi"])
1404
1405        uLogger.debug("Unique list of FIGIs: {}".format(onlyUniqueFIGIs))
1406
1407        return onlyUniqueFIGIs
1408
1409    def GetListOfPrices(self, instruments: list, show: bool = False) -> list:
1410        """
1411        This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!
1412        See limits: https://tinkoff.github.io/investAPI/limits/
1413        If `pricesFile` string is not empty then also save information to this file.
1414
1415        :param instruments: list of strings with tickers or FIGIs.
1416        :param show: if `True` then prints prices to console, if `False` - prints only to file `pricesFile`.
1417        :return: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1418                 One item is dict returned by `SearchByTicker()` or `SearchByFIGI()` methods.
1419        """
1420        if instruments is None or not instruments:
1421            uLogger.error("You must define some of tickers or FIGIs to request it's actual prices!")
1422            raise Exception("Ticker or FIGI required")
1423
1424        onlyUniqueFIGIs = self.GetUniqueFIGIs(instruments)
1425
1426        uLogger.debug("Requesting current prices from Tinkoff Broker server...")
1427
1428        iList = []  # trying to get info and current prices about all unique instruments:
1429        for self.figi in onlyUniqueFIGIs:
1430            iData = self.SearchByFIGI(requestPrice=True)
1431            iList.append(iData)
1432
1433        self.ShowListOfPrices(iList, show)
1434
1435        return iList
1436
1437    def ShowListOfPrices(self, iList: list, show: bool = True) -> str:
1438        """
1439        Show table contains current prices of given instruments.
1440
1441        :param iList: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1442                      One item is dict returned by `SearchByTicker(requestPrice=True)` or by `SearchByFIGI(requestPrice=True)` methods.
1443        :param show: if `True` then prints prices to console, if `False` - prints only to file `pricesFile`.
1444        :return: multilines text in Markdown format as a table contains current prices.
1445        """
1446        infoText = ""
1447
1448        if show or self.pricesFile:
1449            info = [
1450                "# Actual prices at: [{} UTC]\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1451                "| Ticker       | FIGI         | Type       | Prev. close | Last price  | Chg. %   | Day limits min/max  | Actual sell / buy   | Curr. |\n",
1452                "|--------------|--------------|------------|-------------|-------------|----------|---------------------|---------------------|-------|\n",
1453            ]
1454
1455            for item in iList:
1456                info.append("| {:<12} | {:<12} | {:<10} | {:>11} | {:>11} | {:>7}% | {:>19} | {:>19} | {:<5} |\n".format(
1457                    item["ticker"],
1458                    item["figi"],
1459                    item["type"],
1460                    "{:.2f}".format(float(item["currentPrice"]["closePrice"])),
1461                    "{:.2f}".format(float(item["currentPrice"]["lastPrice"])),
1462                    "{}{:.2f}".format("+" if item["currentPrice"]["changes"] > 0 else "", float(item["currentPrice"]["changes"])),
1463                    "{} / {}".format(
1464                        item["currentPrice"]["limitDown"] if item["currentPrice"]["limitDown"] is not None else "N/A",
1465                        item["currentPrice"]["limitUp"] if item["currentPrice"]["limitUp"] is not None else "N/A",
1466                    ),
1467                    "{} / {}".format(
1468                        item["currentPrice"]["sell"][0]["price"] if item["currentPrice"]["sell"] else "N/A",
1469                        item["currentPrice"]["buy"][0]["price"] if item["currentPrice"]["buy"] else "N/A",
1470                    ),
1471                    item["currency"],
1472                ))
1473
1474            infoText = "".join(info)
1475
1476            if show:
1477                uLogger.info("Only instruments with unique FIGIs are shown:\n{}".format(infoText))
1478
1479            if self.pricesFile:
1480                with open(self.pricesFile, "w", encoding="UTF-8") as fH:
1481                    fH.write(infoText)
1482
1483                uLogger.info("Price list for all instruments saved to file: [{}]".format(os.path.abspath(self.pricesFile)))
1484
1485        return infoText
1486
1487    def RequestTradingStatus(self) -> dict:
1488        """
1489        Requesting trading status for the instrument defined by `figi` variable.
1490        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus
1491        Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest
1492
1493        :return: dictionary with trading status attributes. Response example:
1494                 `{"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING",
1495                  "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}`
1496        """
1497        if self.figi is None or not self.figi:
1498            uLogger.error("Variable `figi` must be defined for using this method!")
1499            raise Exception("FIGI required")
1500
1501        uLogger.debug("Requesting current trading status, FIGI: [{}]. Wait, please...".format(self.figi))
1502
1503        self.body = str({"figi": self.figi, "instrumentId": self.figi})
1504        tradingStatusURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetTradingStatus"
1505        tradingStatus = self.SendAPIRequest(tradingStatusURL, reqType="POST")
1506
1507        if self.moreDebug:
1508            uLogger.debug("Records about current trading status successfully received")
1509
1510        return tradingStatus
1511
1512    def RequestPortfolio(self) -> dict:
1513        """
1514        Requesting actual user's portfolio for current `accountId`.
1515        REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio
1516        Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest
1517
1518        :return: dictionary with user's portfolio.
1519        """
1520        if self.accountId is None or not self.accountId:
1521            uLogger.error("Variable `accountId` must be defined for using this method!")
1522            raise Exception("Account ID required")
1523
1524        uLogger.debug("Requesting current actual user's portfolio. Wait, please...")
1525
1526        self.body = str({"accountId": self.accountId})
1527        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPortfolio"
1528        rawPortfolio = self.SendAPIRequest(portfolioURL, reqType="POST")
1529
1530        if self.moreDebug:
1531            uLogger.debug("Records about user's portfolio successfully received")
1532
1533        return rawPortfolio
1534
1535    def RequestPositions(self) -> dict:
1536        """
1537        Requesting open positions by currencies and instruments for current `accountId`.
1538        REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions
1539        Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest
1540
1541        :return: dictionary with open positions by instruments.
1542        """
1543        if self.accountId is None or not self.accountId:
1544            uLogger.error("Variable `accountId` must be defined for using this method!")
1545            raise Exception("Account ID required")
1546
1547        uLogger.debug("Requesting current open positions in currencies and instruments. Wait, please...")
1548
1549        self.body = str({"accountId": self.accountId})
1550        positionsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPositions"
1551        rawPositions = self.SendAPIRequest(positionsURL, reqType="POST")
1552
1553        if self.moreDebug:
1554            uLogger.debug("Records about current open positions successfully received")
1555
1556        return rawPositions
1557
1558    def RequestPendingOrders(self) -> list:
1559        """
1560        Requesting current actual pending orders for current `accountId`.
1561        REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders
1562        Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest
1563
1564        :return: list of dictionaries with pending orders.
1565        """
1566        if self.accountId is None or not self.accountId:
1567            uLogger.error("Variable `accountId` must be defined for using this method!")
1568            raise Exception("Account ID required")
1569
1570        uLogger.debug("Requesting current actual pending orders. Wait, please...")
1571
1572        self.body = str({"accountId": self.accountId})
1573        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/GetOrders"
1574        rawOrders = self.SendAPIRequest(ordersURL, reqType="POST")["orders"]
1575
1576        uLogger.debug("[{}] records about pending orders received".format(len(rawOrders)))
1577
1578        return rawOrders
1579
1580    def RequestStopOrders(self) -> list:
1581        """
1582        Requesting current actual stop orders for current `accountId`.
1583        REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders
1584        Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest
1585
1586        :return: list of dictionaries with stop orders.
1587        """
1588        if self.accountId is None or not self.accountId:
1589            uLogger.error("Variable `accountId` must be defined for using this method!")
1590            raise Exception("Account ID required")
1591
1592        uLogger.debug("Requesting current actual stop orders. Wait, please...")
1593
1594        self.body = str({"accountId": self.accountId})
1595        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/GetStopOrders"
1596        rawStopOrders = self.SendAPIRequest(ordersURL, reqType="POST")["stopOrders"]
1597
1598        uLogger.debug("[{}] records about stop orders received".format(len(rawStopOrders)))
1599
1600        return rawStopOrders
1601
1602    def Overview(self, show: bool = False, details: str = "full") -> dict:
1603        """
1604        Get portfolio: all open positions, orders and some statistics for current `accountId`.
1605        If `overviewFile`, `overviewDigestFile`, `overviewPositionsFile`, `overviewOrdersFile`, `overviewAnalyticsFile`
1606        are defined then also save information to file.
1607
1608        WARNING! It is not recommended to run this method too many times in a loop! The server receives
1609        many requests about the state of the portfolio, and then, based on the received data, a large number
1610        of calculation and statistics are collected.
1611
1612        :param show: if `False` then only dictionary returns, if `True` then show more debug information.
1613        :param details: how detailed should the information be? You should specify one of strings:
1614                        `full` - shows full available information about portfolio status (by default),
1615                        `positions` - shows only open positions,
1616                        `digest` - show a short digest of the portfolio status,
1617                        `analytics` - shows only the analytics section and the distribution of the portfolio by various categories,
1618                        `orders` - shows only sections of open limits and stop orders.
1619        :return: dictionary with client's raw portfolio and some statistics.
1620        """
1621        if self.accountId is None or not self.accountId:
1622            uLogger.error("Variable `accountId` must be defined for using this method!")
1623            raise Exception("Account ID required")
1624
1625        view = {
1626            "raw": {  # --- raw portfolio responses from broker with user portfolio data:
1627                "headers": {},  # list of dictionaries, response headers without "positions" section
1628                "Currencies": [],  # list of dictionaries, open trades with currencies from "positions" section
1629                "Shares": [],  # list of dictionaries, open trades with shares from "positions" section
1630                "Bonds": [],  # list of dictionaries, open trades with bonds from "positions" section
1631                "Etfs": [],  # list of dictionaries, open trades with etfs from "positions" section
1632                "Futures": [],  # list of dictionaries, open trades with futures from "positions" section
1633                "positions": {},  # raw response from broker: dictionary with current available or blocked currencies and instruments for client
1634                "orders": [],  # raw response from broker: list of dictionaries with all pending (market) orders
1635                "stopOrders": [],  # raw response from broker: list of dictionaries with all stop orders
1636                "currenciesCurrentPrices": {"rub": {"name": "Российский рубль", "currentPrice": 1.}},  # dict with prices of all currencies in RUB
1637            },
1638            "stat": {  # --- some statistics calculated using "raw" sections:
1639                "portfolioCostRUB": 0.,  # portfolio cost in RUB (Russian Rouble)
1640                "availableRUB": 0.,  # available rubles (without other currencies)
1641                "blockedRUB": 0.,  # blocked sum in Russian Rouble
1642                "totalChangesRUB": 0.,  # changes for all open trades in RUB
1643                "totalChangesPercentRUB": 0.,  # changes for all open trades in percents
1644                "allCurrenciesCostRUB": 0.,  # costs of all currencies (include rubles) in RUB
1645                "sharesCostRUB": 0.,  # costs of all shares in RUB
1646                "bondsCostRUB": 0.,  # costs of all bonds in RUB
1647                "etfsCostRUB": 0.,  # costs of all etfs in RUB
1648                "futuresCostRUB": 0.,  # costs of all futures in RUB
1649                "Currencies": [],  # list of dictionaries of all currencies statistics
1650                "Shares": [],  # list of dictionaries of all shares statistics
1651                "Bonds": [],  # list of dictionaries of all bonds statistics
1652                "Etfs": [],  # list of dictionaries of all etfs statistics
1653                "Futures": [],  # list of dictionaries of all futures statistics
1654                "orders": [],  # list of dictionaries of all pending (market) orders and it's parameters
1655                "stopOrders": [],  # list of dictionaries of all stop orders and it's parameters
1656                "blockedCurrencies": {},  # dict with blocked instruments and currencies, e.g. {"rub": 1291.87, "usd": 6.21}
1657                "blockedInstruments": {},  # dict with blocked  by FIGI, e.g. {}
1658                "funds": {},  # dict with free funds for trading (total - blocked), by all currencies, e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1659            },
1660            "analytics": {  # --- some analytics of portfolio:
1661                "distrByAssets": {},  # portfolio distribution by assets
1662                "distrByCompanies": {},  # portfolio distribution by companies
1663                "distrBySectors": {},  # portfolio distribution by sectors
1664                "distrByCurrencies": {},  # portfolio distribution by currencies
1665                "distrByCountries": {},  # portfolio distribution by countries
1666            }
1667        }
1668
1669        details = details.lower()
1670        availableDetails = ["full", "positions", "digest", "analytics", "orders"]
1671        if details not in availableDetails:
1672            details = "full"
1673            uLogger.debug("Requested incorrect details! The `details` must be one of this strings: {}. Details parameter set to `full` be default.".format(availableDetails))
1674
1675        uLogger.debug("Requesting portfolio of a client. Wait, please...")
1676
1677        portfolioResponse = self.RequestPortfolio()  # current user's portfolio (dict)
1678        view["raw"]["positions"] = self.RequestPositions()  # current open positions by instruments (dict)
1679        view["raw"]["orders"] = self.RequestPendingOrders()  # current actual pending orders (list)
1680        view["raw"]["stopOrders"] = self.RequestStopOrders()  # current actual stop orders (list)
1681
1682        # save response headers without "positions" section:
1683        for key in portfolioResponse.keys():
1684            if key != "positions":
1685                view["raw"]["headers"][key] = portfolioResponse[key]
1686
1687            else:
1688                continue
1689
1690        # Re-sorting and separating given raw instruments and currencies by type: https://tinkoff.github.io/investAPI/operations/#operation
1691        # Type of instrument must be only one of supported types in TKS_INSTRUMENTS
1692        for item in portfolioResponse["positions"]:
1693            if item["instrumentType"] == "currency":
1694                self.figi = item["figi"]
1695                curr = self.SearchByFIGI(requestPrice=False)
1696
1697                # current price of currency in RUB:
1698                view["raw"]["currenciesCurrentPrices"][curr["nominal"]["currency"]] = {
1699                    "name": curr["name"],
1700                    "currentPrice": NanoToFloat(
1701                        item["currentPrice"]["units"],
1702                        item["currentPrice"]["nano"]
1703                    ),
1704                }
1705
1706                view["raw"]["Currencies"].append(item)
1707
1708            elif item["instrumentType"] == "share":
1709                view["raw"]["Shares"].append(item)
1710
1711            elif item["instrumentType"] == "bond":
1712                view["raw"]["Bonds"].append(item)
1713
1714            elif item["instrumentType"] == "etf":
1715                view["raw"]["Etfs"].append(item)
1716
1717            elif item["instrumentType"] == "futures":
1718                view["raw"]["Futures"].append(item)
1719
1720            else:
1721                continue
1722
1723        # how many volume of currencies (by ISO currency name) are blocked:
1724        for item in view["raw"]["positions"]["blocked"]:
1725            blocked = NanoToFloat(item["units"], item["nano"])
1726            if blocked > 0:
1727                view["stat"]["blockedCurrencies"][item["currency"]] = blocked
1728
1729        # how many volume of instruments (by FIGI) are blocked:
1730        for item in view["raw"]["positions"]["securities"]:
1731            blocked = int(item["blocked"])
1732            if blocked > 0:
1733                view["stat"]["blockedInstruments"][item["figi"]] = blocked
1734
1735        allBlocked = {**view["stat"]["blockedCurrencies"], **view["stat"]["blockedInstruments"]}
1736
1737        if "rub" in allBlocked.keys():
1738            view["stat"]["blockedRUB"] = allBlocked["rub"]  # blocked rubles
1739
1740        # --- saving current total amount in RUB of all currencies (with ruble), shares, bonds, etfs, futures and currencies:
1741        view["stat"]["allCurrenciesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountCurrencies"]["units"], portfolioResponse["totalAmountCurrencies"]["nano"])
1742        view["stat"]["sharesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountShares"]["units"], portfolioResponse["totalAmountShares"]["nano"])
1743        view["stat"]["bondsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountBonds"]["units"], portfolioResponse["totalAmountBonds"]["nano"])
1744        view["stat"]["etfsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountEtf"]["units"], portfolioResponse["totalAmountEtf"]["nano"])
1745        view["stat"]["futuresCostRUB"] = NanoToFloat(portfolioResponse["totalAmountFutures"]["units"], portfolioResponse["totalAmountFutures"]["nano"])
1746        view["stat"]["portfolioCostRUB"] = sum([
1747            view["stat"]["allCurrenciesCostRUB"],
1748            view["stat"]["sharesCostRUB"],
1749            view["stat"]["bondsCostRUB"],
1750            view["stat"]["etfsCostRUB"],
1751            view["stat"]["futuresCostRUB"],
1752        ])
1753
1754        # --- calculating some portfolio statistics:
1755        byComp = {}  # distribution by companies
1756        bySect = {}  # distribution by sectors
1757        byCurr = {}  # distribution by currencies (include RUB)
1758        unknownCountryName = "All other countries"  # default name for instruments without "countryOfRisk" and "countryOfRiskName"
1759        byCountry = {unknownCountryName: {"cost": 0, "percent": 0.}}  # distribution by countries (currencies are included in their countries)
1760
1761        for item in portfolioResponse["positions"]:
1762            self.figi = item["figi"]
1763            instrument = self.SearchByFIGI(requestPrice=False)  # full raw info about instrument by FIGI
1764
1765            if instrument:
1766                if item["instrumentType"] == "currency" and instrument["nominal"]["currency"] in allBlocked.keys():
1767                    blocked = allBlocked[instrument["nominal"]["currency"]]  # blocked volume of currency
1768
1769                elif item["instrumentType"] != "currency" and item["figi"] in allBlocked.keys():
1770                    blocked = allBlocked[item["figi"]]  # blocked volume of other instruments
1771
1772                else:
1773                    blocked = 0
1774
1775                volume = NanoToFloat(item["quantity"]["units"], item["quantity"]["nano"])  # available volume of instrument
1776                lots = NanoToFloat(item["quantityLots"]["units"], item["quantityLots"]["nano"])  # available volume in lots of instrument
1777                direction = "Long" if lots >= 0 else "Short"  # direction of an instrument's position: short or long
1778                curPrice = NanoToFloat(item["currentPrice"]["units"], item["currentPrice"]["nano"])  # current instrument's price
1779                average = NanoToFloat(item["averagePositionPriceFifo"]["units"], item["averagePositionPriceFifo"]["nano"])  # current average position price
1780                profit = NanoToFloat(item["expectedYield"]["units"], item["expectedYield"]["nano"])  # expected profit at current moment
1781                currency = instrument["currency"] if (item["instrumentType"] == "share" or item["instrumentType"] == "etf" or item["instrumentType"] == "future") else instrument["nominal"]["currency"]  # currency name rub, usd, eur etc.
1782                cost = (curPrice + NanoToFloat(item["currentNkd"]["units"], item["currentNkd"]["nano"])) * volume  # current cost of all volume of instrument in basic asset
1783                baseCurrencyName = item["currentPrice"]["currency"]  # name of base currency (rub)
1784                countryName = "[{}] {}".format(instrument["countryOfRisk"], instrument["countryOfRiskName"]) if "countryOfRisk" in instrument.keys() and "countryOfRiskName" in instrument.keys() and instrument["countryOfRisk"] and instrument["countryOfRiskName"] else unknownCountryName
1785                costRUB = cost if item["instrumentType"] == "currency" else cost * view["raw"]["currenciesCurrentPrices"][currency]["currentPrice"]  # cost in rubles
1786                percentCostRUB = 100 * costRUB / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.  # instrument's part in percent of full portfolio cost
1787
1788                statData = {
1789                    "figi": item["figi"],  # FIGI from REST API "GetPortfolio" method
1790                    "ticker": instrument["ticker"],  # ticker by FIGI
1791                    "currency": currency,  # currency name rub, usd, eur etc. for instrument price
1792                    "volume": volume,  # available volume of instrument
1793                    "lots": lots,  # volume in lots of instrument
1794                    "direction": direction,  # direction of an instrument's position: short or long
1795                    "blocked": blocked,  # blocked volume of currency or instrument
1796                    "currentPrice": curPrice,  # current instrument's price in basic asset
1797                    "average": average,  # current average position price
1798                    "cost": cost,  # current cost of all volume of instrument in basic asset
1799                    "baseCurrencyName": baseCurrencyName,  # name of base currency (rub)
1800                    "costRUB": costRUB,  # cost of instrument in ruble
1801                    "percentCostRUB": percentCostRUB,  # instrument's part in percent of full portfolio cost in RUB
1802                    "profit": profit,  # expected profit at current moment
1803                    "percentProfit": 100 * profit / (average * volume) if average != 0 and volume != 0 else 0,  # expected percents of profit at current moment for this instrument
1804                    "sector": instrument["sector"] if "sector" in instrument.keys() and instrument["sector"] else "other",
1805                    "name": instrument["name"] if "name" in instrument.keys() else "",  # human-readable names of instruments
1806                    "isoCurrencyName": instrument["isoCurrencyName"] if "isoCurrencyName" in instrument.keys() else "",  # ISO name for currencies only
1807                    "country": countryName,  # e.g. "[RU] Российская Федерация" or unknownCountryName
1808                    "step": instrument["step"],  # minimum price increment
1809                }
1810
1811                # adding distribution by unique countries:
1812                if statData["country"] not in byCountry.keys():
1813                    byCountry[statData["country"]] = {"cost": costRUB, "percent": percentCostRUB}
1814
1815                else:
1816                    byCountry[statData["country"]]["cost"] += costRUB
1817                    byCountry[statData["country"]]["percent"] += percentCostRUB
1818
1819                if item["instrumentType"] != "currency":
1820                    # adding distribution by unique companies:
1821                    if statData["name"]:
1822                        if statData["name"] not in byComp.keys():
1823                            byComp[statData["name"]] = {"ticker": statData["ticker"], "cost": costRUB, "percent": percentCostRUB}
1824
1825                        else:
1826                            byComp[statData["name"]]["cost"] += costRUB
1827                            byComp[statData["name"]]["percent"] += percentCostRUB
1828
1829                    # adding distribution by unique sectors:
1830                    if statData["sector"] not in bySect.keys():
1831                        bySect[statData["sector"]] = {"cost": costRUB, "percent": percentCostRUB}
1832
1833                    else:
1834                        bySect[statData["sector"]]["cost"] += costRUB
1835                        bySect[statData["sector"]]["percent"] += percentCostRUB
1836
1837                # adding distribution by unique currencies:
1838                if currency not in byCurr.keys():
1839                    byCurr[currency] = {
1840                        "name": view["raw"]["currenciesCurrentPrices"][currency]["name"],
1841                        "cost": costRUB,
1842                        "percent": percentCostRUB
1843                    }
1844
1845                else:
1846                    byCurr[currency]["cost"] += costRUB
1847                    byCurr[currency]["percent"] += percentCostRUB
1848
1849                # saving statistics for every instrument:
1850                if item["instrumentType"] == "currency":
1851                    view["stat"]["Currencies"].append(statData)
1852
1853                    # update dict with free funds for trading (total - blocked) by currencies
1854                    # e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1855                    view["stat"]["funds"][currency] = {
1856                        "total": volume,
1857                        "totalCostRUB": costRUB,  # total volume cost in rubles
1858                        "free": volume - blocked,
1859                        "freeCostRUB": costRUB * ((volume - blocked) / volume) if volume > 0 else 0,  # free volume cost in rubles
1860                    }
1861
1862                elif item["instrumentType"] == "share":
1863                    view["stat"]["Shares"].append(statData)
1864
1865                elif item["instrumentType"] == "bond":
1866                    view["stat"]["Bonds"].append(statData)
1867
1868                elif item["instrumentType"] == "etf":
1869                    view["stat"]["Etfs"].append(statData)
1870
1871                elif item["instrumentType"] == "Futures":
1872                    view["stat"]["Futures"].append(statData)
1873
1874                else:
1875                    continue
1876
1877        # total changes in Russian Ruble:
1878        view["stat"]["availableRUB"] = view["stat"]["allCurrenciesCostRUB"] - sum([item["cost"] for item in view["stat"]["Currencies"]])  # available RUB without other currencies
1879        view["stat"]["totalChangesPercentRUB"] = NanoToFloat(view["raw"]["headers"]["expectedYield"]["units"], view["raw"]["headers"]["expectedYield"]["nano"]) if "expectedYield" in view["raw"]["headers"].keys() else 0.
1880        startCost = view["stat"]["portfolioCostRUB"] / (1 + view["stat"]["totalChangesPercentRUB"] / 100)
1881        view["stat"]["totalChangesRUB"] = view["stat"]["portfolioCostRUB"] - startCost
1882        view["stat"]["funds"]["rub"] = {
1883            "total": view["stat"]["availableRUB"],
1884            "totalCostRUB": view["stat"]["availableRUB"],
1885            "free": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1886            "freeCostRUB": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1887        }
1888
1889        # --- pending orders sector data:
1890        uniquePendingOrdersFIGIs = []  # unique FIGIs of pending orders to avoid many times price requests
1891        uniquePendingOrders = {}  # unique instruments with FIGIs as dictionary keys
1892
1893        for item in view["raw"]["orders"]:
1894            self.figi = item["figi"]
1895
1896            if item["figi"] not in uniquePendingOrdersFIGIs:
1897                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1898
1899                uniquePendingOrdersFIGIs.append(item["figi"])
1900                uniquePendingOrders[item["figi"]] = instrument
1901
1902            else:
1903                instrument = uniquePendingOrders[item["figi"]]
1904
1905            if instrument:
1906                action = TKS_ORDER_DIRECTIONS[item["direction"]]
1907                orderType = TKS_ORDER_TYPES[item["orderType"]]
1908                orderState = TKS_ORDER_STATES[item["executionReportStatus"]]
1909                orderDate = item["orderDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1910
1911                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1912                if item["direction"] == "ORDER_DIRECTION_BUY":
1913                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1914
1915                else:
1916                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1917
1918                # requested price for order execution:
1919                target = NanoToFloat(item["initialSecurityPrice"]["units"], item["initialSecurityPrice"]["nano"])
1920
1921                # necessary changes in percent to reach target from current price:
1922                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1923
1924                view["stat"]["orders"].append({
1925                    "orderID": item["orderId"],  # orderId number parameter of current order
1926                    "figi": item["figi"],  # FIGI identification
1927                    "ticker": instrument["ticker"],  # ticker name by FIGI
1928                    "lotsRequested": item["lotsRequested"],  # requested lots value
1929                    "lotsExecuted": item["lotsExecuted"],  # how many lots are executed
1930                    "currentPrice": lastPrice,  # current instrument's price for defined action
1931                    "targetPrice": target,  # requested price for order execution in base currency
1932                    "baseCurrencyName": item["initialSecurityPrice"]["currency"],  # name of base currency
1933                    "percentChanges": changes,  # changes in percent to target from current price
1934                    "currency": item["currency"],  # instrument's currency name
1935                    "action": action,  # sell / buy / Unknown from TKS_ORDER_DIRECTIONS
1936                    "type": orderType,  # type of order from TKS_ORDER_TYPES
1937                    "status": orderState,  # order status from TKS_ORDER_STATES
1938                    "date": orderDate,  # string with order date and time from UTC format (without nano seconds part)
1939                })
1940
1941        # --- stop orders sector data:
1942        uniqueStopOrdersFIGIs = []  # unique FIGIs of stop orders to avoid many times price requests
1943        uniqueStopOrders = {}  # unique instruments with FIGIs as dictionary keys
1944
1945        for item in view["raw"]["stopOrders"]:
1946            self.figi = item["figi"]
1947
1948            if item["figi"] not in uniqueStopOrdersFIGIs:
1949                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1950
1951                uniqueStopOrdersFIGIs.append(item["figi"])
1952                uniqueStopOrders[item["figi"]] = instrument
1953
1954            else:
1955                instrument = uniqueStopOrders[item["figi"]]
1956
1957            if instrument:
1958                action = TKS_STOP_ORDER_DIRECTIONS[item["direction"]]
1959                orderType = TKS_STOP_ORDER_TYPES[item["orderType"]]
1960                createDate = item["createDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1961
1962                # hack: server response can't contain "expirationTime" key if it is not "Until date" type of stop order
1963                if "expirationTime" in item.keys():
1964                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE"]
1965                    expDate = item["expirationTime"].replace("T", " ").replace("Z", "").split(".")[0]
1966
1967                else:
1968                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL"]
1969                    expDate = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"]
1970
1971                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1972                if item["direction"] == "STOP_ORDER_DIRECTION_BUY":
1973                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1974
1975                else:
1976                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1977
1978                # requested price when stop-order executed:
1979                target = NanoToFloat(item["stopPrice"]["units"], item["stopPrice"]["nano"])
1980
1981                # price for limit-order, set up when stop-order executed:
1982                limit = NanoToFloat(item["price"]["units"], item["price"]["nano"])
1983
1984                # necessary changes in percent to reach target from current price:
1985                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1986
1987                view["stat"]["stopOrders"].append({
1988                    "orderID": item["stopOrderId"],  # stopOrderId number parameter of current stop-order
1989                    "figi": item["figi"],  # FIGI identification
1990                    "ticker": instrument["ticker"],  # ticker name by FIGI
1991                    "lotsRequested": item["lotsRequested"],  # requested lots value
1992                    "currentPrice": lastPrice,  # current instrument's price for defined action
1993                    "targetPrice": target,  # requested price for stop-order execution in base currency
1994                    "limitPrice": limit,  # price for limit-order, set up when stop-order executed, 0 if market order
1995                    "baseCurrencyName": item["stopPrice"]["currency"],  # name of base currency
1996                    "percentChanges": changes,  # changes in percent to target from current price
1997                    "currency": item["currency"],  # instrument's currency name
1998                    "action": action,  # sell / buy / Unknown from TKS_STOP_ORDER_DIRECTIONS
1999                    "type": orderType,  # type of order from TKS_STOP_ORDER_TYPES
2000                    "expType": expType,  # expiration type of stop-order from TKS_STOP_ORDER_EXPIRATION_TYPES
2001                    "createDate": createDate,  # string with created order date and time from UTC format (without nano seconds part)
2002                    "expDate": expDate,  # string with expiration order date and time from UTC format (without nano seconds part)
2003                })
2004
2005        # --- calculating data for analytics section:
2006        # portfolio distribution by assets:
2007        view["analytics"]["distrByAssets"] = {
2008            "Ruble": {
2009                "uniques": 1,
2010                "cost": view["stat"]["availableRUB"],
2011                "percent": 100 * view["stat"]["availableRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2012            },
2013            "Currencies": {
2014                "uniques": len(view["stat"]["Currencies"]),  # all foreign currencies without RUB
2015                "cost": view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"],
2016                "percent": 100 * (view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"]) / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2017            },
2018            "Shares": {
2019                "uniques": len(view["stat"]["Shares"]),
2020                "cost": view["stat"]["sharesCostRUB"],
2021                "percent": 100 * view["stat"]["sharesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2022            },
2023            "Bonds": {
2024                "uniques": len(view["stat"]["Bonds"]),
2025                "cost": view["stat"]["bondsCostRUB"],
2026                "percent": 100 * view["stat"]["bondsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2027            },
2028            "Etfs": {
2029                "uniques": len(view["stat"]["Etfs"]),
2030                "cost": view["stat"]["etfsCostRUB"],
2031                "percent": 100 * view["stat"]["etfsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2032            },
2033            "Futures": {
2034                "uniques": len(view["stat"]["Futures"]),
2035                "cost": view["stat"]["futuresCostRUB"],
2036                "percent": 100 * view["stat"]["futuresCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2037            },
2038        }
2039
2040        # portfolio distribution by companies:
2041        view["analytics"]["distrByCompanies"]["All money cash"] = {
2042            "ticker": "",
2043            "cost": view["stat"]["allCurrenciesCostRUB"],
2044            "percent": 100 * view["stat"]["allCurrenciesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2045        }
2046        view["analytics"]["distrByCompanies"].update(byComp)
2047
2048        # portfolio distribution by sectors:
2049        view["analytics"]["distrBySectors"]["All money cash"] = {
2050            "cost": view["analytics"]["distrByCompanies"]["All money cash"]["cost"],
2051            "percent": view["analytics"]["distrByCompanies"]["All money cash"]["percent"],
2052        }
2053        view["analytics"]["distrBySectors"].update(bySect)
2054
2055        # portfolio distribution by currencies:
2056        if "rub" not in view["analytics"]["distrByCurrencies"].keys():
2057            view["analytics"]["distrByCurrencies"]["rub"] = {"name": "Российский рубль", "cost": 0, "percent": 0}
2058
2059            if self.moreDebug:
2060                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by currencies` section. Server not returned current available rubles!")
2061
2062        view["analytics"]["distrByCurrencies"].update(byCurr)
2063        view["analytics"]["distrByCurrencies"]["rub"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2064        view["analytics"]["distrByCurrencies"]["rub"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2065
2066        # portfolio distribution by countries:
2067        if "[RU] Российская Федерация" not in view["analytics"]["distrByCountries"].keys():
2068            view["analytics"]["distrByCountries"]["[RU] Российская Федерация"] = {"cost": 0, "percent": 0}
2069
2070            if self.moreDebug:
2071                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by countries` section. Server not returned current available rubles!")
2072
2073        view["analytics"]["distrByCountries"].update(byCountry)
2074        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2075        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2076
2077        # --- Prepare text statistics overview in human-readable:
2078        if show:
2079            # Whatever the value `details`, header not changes:
2080            info = [
2081                "# Client's portfolio\n\n",
2082                "* **Actual date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
2083                "* **Account ID:** [{}]\n".format(self.accountId),
2084            ]
2085
2086            if details in ["full", "positions", "digest"]:
2087                info.extend([
2088                    "* **Portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2089                    "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n\n".format(
2090                        "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2091                        view["stat"]["totalChangesRUB"],
2092                        "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2093                        view["stat"]["totalChangesPercentRUB"],
2094                    ),
2095                ])
2096
2097            if details in ["full", "positions"]:
2098                info.extend([
2099                    "## Open positions\n\n",
2100                    "| Ticker [FIGI]               | Volume (blocked)                | Lots     | Curr. price  | Avg. price   | Current volume cost | Profit (%)                   |\n",
2101                    "|-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|------------------------------|\n",
2102                    "| Ruble                       | {:>31} |          |              |              |                     |                              |\n".format(
2103                        "{:.2f} ({:.2f}) rub".format(
2104                            view["stat"]["availableRUB"],
2105                            view["stat"]["blockedRUB"],
2106                        )
2107                    )
2108                ])
2109
2110                def _SplitStr(CostRUB: float = 0, typeStr: str = "", noTradeStr: str = "") -> list:
2111                    return [
2112                        "|                             |                                 |          |              |              |                     |                              |\n",
2113                        "| {:<27} |                                 |          |              |              | {:>19} |                              |\n".format(
2114                            noTradeStr if noTradeStr else typeStr,
2115                            "" if noTradeStr else "{:.2f} RUB".format(CostRUB),
2116                        ),
2117                    ]
2118
2119                def _InfoStr(data: dict, showCurrencyName: bool = False) -> str:
2120                    return "| {:<27} | {:>31} | {:<8} | {:>12} | {:>12} | {:>19} | {:<28} |\n".format(
2121                        "{} [{}]".format(data["ticker"], data["figi"]),
2122                        "{:.2f} ({:.2f}) {}".format(
2123                            data["volume"],
2124                            data["blocked"],
2125                            data["currency"],
2126                        ) if showCurrencyName else "{:.0f} ({:.0f})".format(
2127                            data["volume"],
2128                            data["blocked"],
2129                        ),
2130                        "{:.4f}".format(data["lots"]) if showCurrencyName else "{:.0f}".format(data["lots"]),
2131                        "{:.2f} {}".format(data["currentPrice"], data["baseCurrencyName"]) if data["currentPrice"] > 0 else "n/a",
2132                        "{:.2f} {}".format(data["average"], data["baseCurrencyName"]) if data["average"] > 0 else "n/a",
2133                        "{:.2f} {}".format(data["cost"], data["baseCurrencyName"]),
2134                        "{}{:.2f} {} ({}{:.2f}%)".format(
2135                            "+" if data["profit"] > 0 else "",
2136                            data["profit"], data["baseCurrencyName"],
2137                            "+" if data["percentProfit"] > 0 else "",
2138                            data["percentProfit"],
2139                        ),
2140                    )
2141
2142                # --- Show currencies section:
2143                if view["stat"]["Currencies"]:
2144                    info.extend(_SplitStr(CostRUB=view["analytics"]["distrByAssets"]["Currencies"]["cost"], typeStr="**Currencies:**"))
2145                    for item in view["stat"]["Currencies"]:
2146                        info.append(_InfoStr(item, showCurrencyName=True))
2147
2148                else:
2149                    info.extend(_SplitStr(noTradeStr="**Currencies:** no trades"))
2150
2151                # --- Show shares section:
2152                if view["stat"]["Shares"]:
2153                    info.extend(_SplitStr(CostRUB=view["stat"]["sharesCostRUB"], typeStr="**Shares:**"))
2154
2155                    for item in view["stat"]["Shares"]:
2156                        info.append(_InfoStr(item))
2157
2158                else:
2159                    info.extend(_SplitStr(noTradeStr="**Shares:** no trades"))
2160
2161                # --- Show bonds section:
2162                if view["stat"]["Bonds"]:
2163                    info.extend(_SplitStr(CostRUB=view["stat"]["bondsCostRUB"], typeStr="**Bonds:**"))
2164
2165                    for item in view["stat"]["Bonds"]:
2166                        info.append(_InfoStr(item))
2167
2168                else:
2169                    info.extend(_SplitStr(noTradeStr="**Bonds:** no trades"))
2170
2171                # --- Show etfs section:
2172                if view["stat"]["Etfs"]:
2173                    info.extend(_SplitStr(CostRUB=view["stat"]["etfsCostRUB"], typeStr="**Etfs:**"))
2174
2175                    for item in view["stat"]["Etfs"]:
2176                        info.append(_InfoStr(item))
2177
2178                else:
2179                    info.extend(_SplitStr(noTradeStr="**Etfs:** no trades"))
2180
2181                # --- Show futures section:
2182                if view["stat"]["Futures"]:
2183                    info.extend(_SplitStr(CostRUB=view["stat"]["futuresCostRUB"], typeStr="**Futures:**"))
2184
2185                    for item in view["stat"]["Futures"]:
2186                        info.append(_InfoStr(item))
2187
2188                else:
2189                    info.extend(_SplitStr(noTradeStr="**Futures:** no trades"))
2190
2191            if details in ["full", "orders"]:
2192                # --- Show pending orders section:
2193                if view["stat"]["orders"]:
2194                    info.extend([
2195                        "\n## Opened pending limit-orders: {}\n".format(len(view["stat"]["orders"])),
2196                        "\n| Ticker [FIGI]               | Order ID       | Lots (exec.) | Current price (% delta) | Target price  | Action    | Type      | Create date (UTC)       |\n",
2197                        "|-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|-------------------------|\n",
2198                    ])
2199
2200                    for item in view["stat"]["orders"]:
2201                        info.append("| {:<27} | {:<14} | {:<12} | {:>23} | {:>13} | {:<9} | {:<9} | {:<23} |\n".format(
2202                            "{} [{}]".format(item["ticker"], item["figi"]),
2203                            item["orderID"],
2204                            "{} ({})".format(item["lotsRequested"], item["lotsExecuted"]),
2205                            "{} {} ({}{:.2f}%)".format(
2206                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2207                                item["baseCurrencyName"],
2208                                "+" if item["percentChanges"] > 0 else "",
2209                                float(item["percentChanges"]),
2210                            ),
2211                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2212                            item["action"],
2213                            item["type"],
2214                            item["date"],
2215                        ))
2216
2217                else:
2218                    info.append("\n## Total pending limit-orders: 0\n")
2219
2220                # --- Show stop orders section:
2221                if view["stat"]["stopOrders"]:
2222                    info.extend([
2223                        "\n## Opened stop-orders: {}\n".format(len(view["stat"]["stopOrders"])),
2224                        "\n| Ticker [FIGI]               | Stop order ID                        | Lots   | Current price (% delta) | Target price  | Limit price   | Action    | Type        | Expire type  | Create date (UTC)   | Expiration (UTC)    |\n",
2225                        "|-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|---------------------|\n",
2226                    ])
2227
2228                    for item in view["stat"]["stopOrders"]:
2229                        info.append("| {:<27} | {:<14} | {:<6} | {:>23} | {:>13} | {:>13} | {:<9} | {:<11} | {:<12} | {:<19} | {:<19} |\n".format(
2230                            "{} [{}]".format(item["ticker"], item["figi"]),
2231                            item["orderID"],
2232                            item["lotsRequested"],
2233                            "{} {} ({}{:.2f}%)".format(
2234                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2235                                item["baseCurrencyName"],
2236                                "+" if item["percentChanges"] > 0 else "",
2237                                float(item["percentChanges"]),
2238                            ),
2239                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2240                            "{:.2f} {}".format(float(item["limitPrice"]), item["baseCurrencyName"]) if item["limitPrice"] and item["limitPrice"] != item["targetPrice"] else TKS_ORDER_TYPES["ORDER_TYPE_MARKET"],
2241                            item["action"],
2242                            item["type"],
2243                            item["expType"],
2244                            item["createDate"],
2245                            item["expDate"],
2246                        ))
2247
2248                else:
2249                    info.append("\n## Total stop-orders: 0\n")
2250
2251            if details in ["full", "analytics"]:
2252                # -- Show analytics section:
2253                if view["stat"]["portfolioCostRUB"] > 0:
2254                    info.extend([
2255                        "\n# Analytics\n"
2256                        "\n* **Current total portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2257                        "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n".format(
2258                            "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2259                            view["stat"]["totalChangesRUB"],
2260                            "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2261                            view["stat"]["totalChangesPercentRUB"],
2262                        ),
2263                        "\n## Portfolio distribution by assets\n"
2264                        "\n| Type       | Uniques | Percent | Current cost       |\n",
2265                        "|------------|---------|---------|--------------------|\n",
2266                    ])
2267
2268                    for key in view["analytics"]["distrByAssets"].keys():
2269                        if view["analytics"]["distrByAssets"][key]["cost"] > 0:
2270                            info.append("| {:<10} | {:<7} | {:<7} | {:<18} |\n".format(
2271                                key,
2272                                view["analytics"]["distrByAssets"][key]["uniques"],
2273                                "{:.2f}%".format(view["analytics"]["distrByAssets"][key]["percent"]),
2274                                "{:.2f} rub".format(view["analytics"]["distrByAssets"][key]["cost"]),
2275                            ))
2276
2277                    maxLenNames = 3 + max([len(company) + len(view["analytics"]["distrByCompanies"][company]["ticker"]) for company in view["analytics"]["distrByCompanies"].keys()])
2278                    info.extend([
2279                        "\n## Portfolio distribution by companies\n"
2280                        "\n| Company{} | Percent | Current cost       |\n".format(" " * (maxLenNames - 7)),
2281                        "|--------{}-|---------|--------------------|\n".format("-" * (maxLenNames - 7)),
2282                    ])
2283
2284                    for company in view["analytics"]["distrByCompanies"].keys():
2285                        if view["analytics"]["distrByCompanies"][company]["cost"] > 0:
2286                            nameLen = len(company) + len(view["analytics"]["distrByCompanies"][company]["ticker"])
2287                            info.append("| {} | {:<7} | {:<18} |\n".format(
2288                                "{}{}{}".format(
2289                                    "[{}] ".format(view["analytics"]["distrByCompanies"][company]["ticker"]) if view["analytics"]["distrByCompanies"][company]["ticker"] else "",
2290                                    company,
2291                                    "" if nameLen == maxLenNames else "{}".format(" " * (maxLenNames - nameLen - 3) if view["analytics"]["distrByCompanies"][company]["ticker"] else " " * (maxLenNames - nameLen)),
2292                                ),
2293                                "{:.2f}%".format(view["analytics"]["distrByCompanies"][company]["percent"]),
2294                                "{:.2f} rub".format(view["analytics"]["distrByCompanies"][company]["cost"]),
2295                            ))
2296
2297                    maxLenSectors = max([len(sector) for sector in view["analytics"]["distrBySectors"].keys()])
2298                    info.extend([
2299                        "\n## Portfolio distribution by sectors\n"
2300                        "\n| Sector{} | Percent | Current cost       |\n".format(" " * (maxLenSectors - 6)),
2301                        "|-------{}-|---------|--------------------|\n".format("-" * (maxLenSectors - 6)),
2302                    ])
2303
2304                    for sector in view["analytics"]["distrBySectors"].keys():
2305                        if view["analytics"]["distrBySectors"][sector]["cost"] > 0:
2306                            info.append("| {}{} | {:<7} | {:<18} |\n".format(
2307                                sector,
2308                                "" if len(sector) == maxLenSectors else " " * (maxLenSectors - len(sector)),
2309                                "{:.2f}%".format(view["analytics"]["distrBySectors"][sector]["percent"]),
2310                                "{:.2f} rub".format(view["analytics"]["distrBySectors"][sector]["cost"]),
2311                            ))
2312
2313                    maxLenMoney = 3 + max([len(currency) + len(view["analytics"]["distrByCurrencies"][currency]["name"]) for currency in view["analytics"]["distrByCurrencies"].keys()])
2314                    info.extend([
2315                        "\n## Portfolio distribution by currencies\n"
2316                        "\n| Instruments currencies{} | Percent | Current cost       |\n".format(" " * (maxLenMoney - 22)),
2317                        "|-----------------------{}-|---------|--------------------|\n".format("-" * (maxLenMoney - 22)),
2318                    ])
2319
2320                    for curr in view["analytics"]["distrByCurrencies"].keys():
2321                        if view["analytics"]["distrByCurrencies"][curr]["cost"] > 0:
2322                            nameLen = 3 + len(curr) + len(view["analytics"]["distrByCurrencies"][curr]["name"])
2323                            info.append("| {} | {:<7} | {:<18} |\n".format(
2324                                "[{}] {}{}".format(
2325                                    curr,
2326                                    view["analytics"]["distrByCurrencies"][curr]["name"],
2327                                    "" if nameLen == maxLenMoney else " " * (maxLenMoney - nameLen),
2328                                ),
2329                                "{:.2f}%".format(view["analytics"]["distrByCurrencies"][curr]["percent"]),
2330                                "{:.2f} rub".format(view["analytics"]["distrByCurrencies"][curr]["cost"]),
2331                            ))
2332
2333                    maxLenCountry = max(17, max([len(country) for country in view["analytics"]["distrByCountries"].keys()]))
2334                    info.extend([
2335                        "\n## Portfolio distribution by countries\n"
2336                        "\n| Assets by country{} | Percent | Current cost       |\n".format(" " * (maxLenCountry - 17)),
2337                        "|------------------{}-|---------|--------------------|\n".format("-" * (maxLenCountry - 17)),
2338                    ])
2339
2340                    for country in view["analytics"]["distrByCountries"].keys():
2341                        if view["analytics"]["distrByCountries"][country]["cost"] > 0:
2342                            nameLen = len(country)
2343                            info.append("| {} | {:<7} | {:<18} |\n".format(
2344                                "{}{}".format(
2345                                    country,
2346                                    "" if nameLen == maxLenCountry else " " * (maxLenCountry - nameLen),
2347                                ),
2348                                "{:.2f}%".format(view["analytics"]["distrByCountries"][country]["percent"]),
2349                                "{:.2f} rub".format(view["analytics"]["distrByCountries"][country]["cost"]),
2350                            ))
2351
2352            infoText = "".join(info)
2353
2354            uLogger.info(infoText)
2355
2356            if details == "full" and self.overviewFile:
2357                filename = self.overviewFile
2358
2359            elif details == "digest" and self.overviewDigestFile:
2360                filename = self.overviewDigestFile
2361
2362            elif details == "positions" and self.overviewPositionsFile:
2363                filename = self.overviewPositionsFile
2364
2365            elif details == "orders" and self.overviewOrdersFile:
2366                filename = self.overviewOrdersFile
2367
2368            elif details == "analytics" and self.overviewAnalyticsFile:
2369                filename = self.overviewAnalyticsFile
2370
2371            else:
2372                filename = ""
2373
2374            if filename:
2375                with open(filename, "w", encoding="UTF-8") as fH:
2376                    fH.write(infoText)
2377
2378                uLogger.info("Client's portfolio was saved to file: [{}]".format(os.path.abspath(filename)))
2379
2380        return view
2381
2382    def Deals(self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True) -> tuple[list[dict], dict]:
2383        """
2384        Returns history operations between two given dates for current `accountId`.
2385        If `reportFile` string is not empty then also save human-readable report.
2386        Shows some statistical data of closed positions.
2387
2388        :param start: see docstring in `GetDatesAsString()` method
2389        :param end: see docstring in `GetDatesAsString()` method
2390        :param show: if `True` then also prints all records to the console.
2391        :param showCancelled: if `False` then remove information about cancelled operations from the deals report.
2392        :return: original list of dictionaries with history of deals records from API ("operations" key):
2393                 https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2394                 and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.
2395        """
2396        if self.accountId is None or not self.accountId:
2397            uLogger.error("Variable `accountId` must be defined for using this method!")
2398            raise Exception("Account ID required")
2399
2400        startDate, endDate = GetDatesAsString(start, end)  # Example: ("2000-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2401
2402        uLogger.debug("Requesting history of a client's operations. Wait, please...")
2403
2404        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2405        dealsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetOperations"
2406        self.body = str({"accountId": self.accountId, "from": startDate, "to": endDate})
2407        ops = self.SendAPIRequest(dealsURL, reqType="POST")["operations"]  # list of dict: operations returns by broker
2408        customStat = {}  # custom statistics in additional to responseJSON
2409
2410        # --- output report in human-readable format:
2411        if show or self.reportFile:
2412            splitLine1 = "|                            |                               |                              |                      |                        |\n"  # Summary section
2413            splitLine2 = "|                     |              |              |            |           |                 |            |                                                                    |\n"  # Operations section
2414            nextDay = ""
2415
2416            info = ["# Client's operations\n\n* **Period:** from [{}] to [{}]\n\n## Summary (operations executed only)\n\n".format(startDate.split("T")[0], endDate.split("T")[0])]
2417
2418            if len(ops) > 0:
2419                customStat = {
2420                    "opsCount": 0,  # total operations count
2421                    "buyCount": 0,  # buy operations
2422                    "sellCount": 0,  # sell operations
2423                    "buyTotal": {"rub": 0.},  # Buy sums in different currencies
2424                    "sellTotal": {"rub": 0.},  # Sell sums in different currencies
2425                    "payIn": {"rub": 0.},  # Deposit brokerage account
2426                    "payOut": {"rub": 0.},  # Withdrawals
2427                    "divs": {"rub": 0.},  # Dividends income
2428                    "coupons": {"rub": 0.},  # Coupon's income
2429                    "brokerCom": {"rub": 0.},  # Service commissions
2430                    "serviceCom": {"rub": 0.},  # Service commissions
2431                    "marginCom": {"rub": 0.},  # Margin commissions
2432                    "allTaxes": {"rub": 0.},  # Sum of withholding taxes and corrections
2433                }
2434
2435                # --- calculating statistics depends on operations type in TKS_OPERATION_TYPES:
2436                for item in ops:
2437                    if item["state"] == "OPERATION_STATE_EXECUTED":
2438                        payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2439
2440                        # count buy operations:
2441                        if "_BUY" in item["operationType"]:
2442                            customStat["buyCount"] += 1
2443
2444                            if item["payment"]["currency"] in customStat["buyTotal"].keys():
2445                                customStat["buyTotal"][item["payment"]["currency"]] += payment
2446
2447                            else:
2448                                customStat["buyTotal"][item["payment"]["currency"]] = payment
2449
2450                        # count sell operations:
2451                        elif "_SELL" in item["operationType"]:
2452                            customStat["sellCount"] += 1
2453
2454                            if item["payment"]["currency"] in customStat["sellTotal"].keys():
2455                                customStat["sellTotal"][item["payment"]["currency"]] += payment
2456
2457                            else:
2458                                customStat["sellTotal"][item["payment"]["currency"]] = payment
2459
2460                        # count incoming operations:
2461                        elif item["operationType"] in ["OPERATION_TYPE_INPUT"]:
2462                            if item["payment"]["currency"] in customStat["payIn"].keys():
2463                                customStat["payIn"][item["payment"]["currency"]] += payment
2464
2465                            else:
2466                                customStat["payIn"][item["payment"]["currency"]] = payment
2467
2468                        # count withdrawals operations:
2469                        elif item["operationType"] in ["OPERATION_TYPE_OUTPUT"]:
2470                            if item["payment"]["currency"] in customStat["payOut"].keys():
2471                                customStat["payOut"][item["payment"]["currency"]] += payment
2472
2473                            else:
2474                                customStat["payOut"][item["payment"]["currency"]] = payment
2475
2476                        # count dividends income:
2477                        elif item["operationType"] in ["OPERATION_TYPE_DIVIDEND", "OPERATION_TYPE_DIVIDEND_TRANSFER", "OPERATION_TYPE_DIV_EXT"]:
2478                            if item["payment"]["currency"] in customStat["divs"].keys():
2479                                customStat["divs"][item["payment"]["currency"]] += payment
2480
2481                            else:
2482                                customStat["divs"][item["payment"]["currency"]] = payment
2483
2484                        # count coupon's income:
2485                        elif item["operationType"] in ["OPERATION_TYPE_COUPON", "OPERATION_TYPE_BOND_REPAYMENT_FULL", "OPERATION_TYPE_BOND_REPAYMENT"]:
2486                            if item["payment"]["currency"] in customStat["coupons"].keys():
2487                                customStat["coupons"][item["payment"]["currency"]] += payment
2488
2489                            else:
2490                                customStat["coupons"][item["payment"]["currency"]] = payment
2491
2492                        # count broker commissions:
2493                        elif item["operationType"] in ["OPERATION_TYPE_BROKER_FEE", "OPERATION_TYPE_SUCCESS_FEE", "OPERATION_TYPE_TRACK_MFEE", "OPERATION_TYPE_TRACK_PFEE"]:
2494                            if item["payment"]["currency"] in customStat["brokerCom"].keys():
2495                                customStat["brokerCom"][item["payment"]["currency"]] += payment
2496
2497                            else:
2498                                customStat["brokerCom"][item["payment"]["currency"]] = payment
2499
2500                        # count service commissions:
2501                        elif item["operationType"] in ["OPERATION_TYPE_SERVICE_FEE"]:
2502                            if item["payment"]["currency"] in customStat["serviceCom"].keys():
2503                                customStat["serviceCom"][item["payment"]["currency"]] += payment
2504
2505                            else:
2506                                customStat["serviceCom"][item["payment"]["currency"]] = payment
2507
2508                        # count margin commissions:
2509                        elif item["operationType"] in ["OPERATION_TYPE_MARGIN_FEE"]:
2510                            if item["payment"]["currency"] in customStat["marginCom"].keys():
2511                                customStat["marginCom"][item["payment"]["currency"]] += payment
2512
2513                            else:
2514                                customStat["marginCom"][item["payment"]["currency"]] = payment
2515
2516                        # count withholding taxes:
2517                        elif "_TAX" in item["operationType"]:
2518                            if item["payment"]["currency"] in customStat["allTaxes"].keys():
2519                                customStat["allTaxes"][item["payment"]["currency"]] += payment
2520
2521                            else:
2522                                customStat["allTaxes"][item["payment"]["currency"]] = payment
2523
2524                        else:
2525                            continue
2526
2527                customStat["opsCount"] += customStat["buyCount"] + customStat["sellCount"]
2528
2529                # --- view "Actions" lines:
2530                info.extend([
2531                    "| Report sections            |                               |                              |                      |                        |\n",
2532                    "|----------------------------|-------------------------------|------------------------------|----------------------|------------------------|\n",
2533                    "| **Actions:**               | Trades: {:<21} | Trading volumes:             |                      |                        |\n".format(customStat["opsCount"]),
2534                    "|                            |   Buy: {:<22} | {:<28} |                      |                        |\n".format(
2535                        "{} ({:.1f}%)".format(customStat["buyCount"], 100 * customStat["buyCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2536                        "  rub, buy: {:<16}".format("{:.2f}".format(customStat["buyTotal"]["rub"])) if customStat["buyTotal"]["rub"] != 0 else "  —",
2537                    ),
2538                    "|                            |   Sell: {:<21} | {:<28} |                      |                        |\n".format(
2539                        "{} ({:.1f}%)".format(customStat["sellCount"], 100 * customStat["sellCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2540                        "  rub, sell: {:<13}".format("+{:.2f}".format(customStat["sellTotal"]["rub"])) if customStat["sellTotal"]["rub"] != 0 else "  —",
2541                    ),
2542                ])
2543
2544                opsKeys = sorted(list(set(list(customStat["buyTotal"].keys()) + list(customStat["sellTotal"].keys()))))
2545                for key in opsKeys:
2546                    if key == "rub":
2547                        continue
2548
2549                    info.extend([
2550                        "|                            |                               | {:<28} |                      |                        |\n".format(
2551                            "  {}, buy: {:<16}".format(key, "{:.2f}".format(customStat["buyTotal"][key]) if key and key in customStat["buyTotal"].keys() and customStat["buyTotal"][key] != 0 else 0)
2552                        ),
2553                        "|                            |                               | {:<28} |                      |                        |\n".format(
2554                            "  {}, sell: {:<13}".format(key, "+{:.2f}".format(customStat["sellTotal"][key]) if key and key in customStat["sellTotal"].keys() and customStat["sellTotal"][key] != 0 else 0)
2555                        ),
2556                    ])
2557
2558                info.append(splitLine1)
2559
2560                def _InfoStr(data1: dict, data2: dict, data3: dict, data4: dict, cur: str = "") -> str:
2561                    return "|                            | {:<29} | {:<28} | {:<20} | {:<22} |\n".format(
2562                            "  {}: {}{:.2f}".format(cur, "+" if data1[cur] > 0 else "", data1[cur]) if cur and cur in data1.keys() and data1[cur] != 0 else "  —",
2563                            "  {}: {}{:.2f}".format(cur, "+" if data2[cur] > 0 else "", data2[cur]) if cur and cur in data2.keys() and data2[cur] != 0 else "  —",
2564                            "  {}: {}{:.2f}".format(cur, "+" if data3[cur] > 0 else "", data3[cur]) if cur and cur in data3.keys() and data3[cur] != 0 else "  —",
2565                            "  {}: {}{:.2f}".format(cur, "+" if data4[cur] > 0 else "", data4[cur]) if cur and cur in data4.keys() and data4[cur] != 0 else "  —",
2566                    )
2567
2568                # --- view "Payments" lines:
2569                info.append("| **Payments:**              | Deposit on broker account:    | Withdrawals:                 | Dividends income:    | Coupons income:        |\n")
2570                paymentsKeys = sorted(list(set(list(customStat["payIn"].keys()) + list(customStat["payOut"].keys()) + list(customStat["divs"].keys()) + list(customStat["coupons"].keys()))))
2571
2572                for key in paymentsKeys:
2573                    info.append(_InfoStr(customStat["payIn"], customStat["payOut"], customStat["divs"], customStat["coupons"], key))
2574
2575                info.append(splitLine1)
2576
2577                # --- view "Commissions and taxes" lines:
2578                info.append("| **Commissions and taxes:** | Broker commissions:           | Service commissions:         | Margin commissions:  | All taxes/corrections: |\n")
2579                comKeys = sorted(list(set(list(customStat["brokerCom"].keys()) + list(customStat["serviceCom"].keys()) + list(customStat["marginCom"].keys()) + list(customStat["allTaxes"].keys()))))
2580
2581                for key in comKeys:
2582                    info.append(_InfoStr(customStat["brokerCom"], customStat["serviceCom"], customStat["marginCom"], customStat["allTaxes"], key))
2583
2584                info.append(splitLine1)
2585
2586                info.extend([
2587                    "\n## All operations{}\n\n".format("" if showCancelled else " (without cancelled status)"),
2588                    "| Date and time       | FIGI         | Ticker       | Asset      | Value     | Payment         | Status     | Operation type                                                     |\n",
2589                    "|---------------------|--------------|--------------|------------|-----------|-----------------|------------|--------------------------------------------------------------------|\n",
2590                ])
2591
2592            else:
2593                info.append("Broker returned no operations during this period\n")
2594
2595            # --- view "Operations" section:
2596            for item in ops:
2597                if not showCancelled and TKS_OPERATION_STATES[item["state"]] == TKS_OPERATION_STATES["OPERATION_STATE_CANCELED"]:
2598                    continue
2599
2600                else:
2601                    self.figi = item["figi"] if item["figi"] else ""
2602                    payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2603                    instrument = self.SearchByFIGI(requestPrice=False) if self.figi else {}
2604
2605                    # group of deals during one day:
2606                    if nextDay and item["date"].split("T")[0] != nextDay:
2607                        info.append(splitLine2)
2608                        nextDay = ""
2609
2610                    else:
2611                        nextDay = item["date"].split("T")[0]  # saving current day for splitting
2612
2613                    info.append("| {:<19} | {:<12} | {:<12} | {:<10} | {:<9} | {:>15} | {:<10} | {:<66} |\n".format(
2614                        item["date"].replace("T", " ").replace("Z", "").split(".")[0],
2615                        self.figi if self.figi else "—",
2616                        instrument["ticker"] if instrument else "—",
2617                        instrument["type"] if instrument else "—",
2618                        item["quantity"] if int(item["quantity"]) > 0 else "—",
2619                        "{}{:.2f} {}".format("+" if payment > 0 else "", payment, item["payment"]["currency"]) if payment != 0 else "—",
2620                        TKS_OPERATION_STATES[item["state"]],
2621                        TKS_OPERATION_TYPES[item["operationType"]],
2622                    ))
2623
2624            infoText = "".join(info)
2625
2626            if show:
2627                if self.moreDebug:
2628                    uLogger.debug("Records about history of a client's operations successfully received")
2629
2630                uLogger.info(infoText)
2631
2632            if self.reportFile:
2633                with open(self.reportFile, "w", encoding="UTF-8") as fH:
2634                    fH.write(infoText)
2635
2636                uLogger.info("History of a client's operations are saved to file: [{}]".format(os.path.abspath(self.reportFile)))
2637
2638        return ops, customStat
2639
2640    def History(self, start: str = None, end: str = None, interval: str = "hour", onlyMissing: bool = False, csvSep: str = ",", show: bool = False) -> pd.DataFrame:
2641        """
2642        This method returns last history candles of the current instrument defined by `ticker` or `figi` (FIGI id).
2643
2644        History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`.
2645        Warning! Broker server used ISO UTC time by default.
2646
2647        If `historyFile` is not `None` then method save history to file, otherwise return only Pandas DataFrame.
2648        Also, `historyFile` used to update history with `onlyMissing` parameter.
2649
2650        See also: `LoadHistory()` and `ShowHistoryChart()` methods.
2651
2652        :param start: see docstring in `GetDatesAsString()` method.
2653        :param end: see docstring in `GetDatesAsString()` method.
2654        :param interval: this is a candle interval. Current available values are `"1min"`, `"5min"`, `"15min"`,
2655                         `"hour"`, `"day"`. Default: `"hour"`.
2656        :param onlyMissing: if `True` then add only last missing candles, do not request all history length from `start`.
2657                            False by default. Warning! History appends only from last candle to current time
2658                            with always update last candle!
2659        :param csvSep: separator if csv-file is used, `,` by default.
2660        :param show: if `True` then also prints Pandas DataFrame to the console.
2661        :return: Pandas DataFrame with prices history. Headers of columns are defined by default:
2662                 `["date", "time", "open", "high", "low", "close", "volume"]`.
2663        """
2664        strStartDate, strEndDate = GetDatesAsString(start, end)  # example: ("2020-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2665        headers = ["date", "time", "open", "high", "low", "close", "volume"]  # sequence and names of column headers
2666        history = None  # empty pandas object for history
2667
2668        if interval not in TKS_CANDLE_INTERVALS.keys():
2669            uLogger.error("Interval parameter must be string with current available values: `1min`, `5min`, `15min`, `hour` and `day`.")
2670            raise Exception("Incorrect value")
2671
2672        if not (self.ticker or self.figi):
2673            uLogger.error("Ticker or FIGI must be defined!")
2674            raise Exception("Ticker or FIGI required")
2675
2676        if self.ticker and not self.figi:
2677            instrumentByTicker = self.SearchByTicker(requestPrice=False)
2678            self.figi = instrumentByTicker["figi"] if instrumentByTicker else ""
2679
2680        if self.figi and not self.ticker:
2681            instrumentByFIGI = self.SearchByFIGI(requestPrice=False)
2682            self.ticker = instrumentByFIGI["ticker"] if instrumentByFIGI else ""
2683
2684        dtStart = datetime.strptime(strStartDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from start time string
2685        dtEnd = datetime.strptime(strEndDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from end time string
2686        if interval.lower() != "day":
2687            dtEnd += timedelta(seconds=1)  # adds 1 sec for requests, because day end returned by `GetDatesAsString()` as 23:59:59
2688
2689        delta = dtEnd - dtStart  # current UTC time minus last time in file
2690        deltaMinutes = delta.days * 1440 + delta.seconds // 60  # minutes between start and end dates
2691
2692        # calculate history length in candles:
2693        length = deltaMinutes // TKS_CANDLE_INTERVALS[interval][1]
2694        if deltaMinutes % TKS_CANDLE_INTERVALS[interval][1] > 0:
2695            length += 1  # to avoid fraction time
2696
2697        # calculate data blocks count:
2698        blocks = 1 if length < TKS_CANDLE_INTERVALS[interval][2] else 1 + length // TKS_CANDLE_INTERVALS[interval][2]
2699
2700        uLogger.debug("Original requested time period in local time: from [{}] to [{}]".format(start, end))
2701        uLogger.debug("Requested time period is about from [{}] UTC to [{}] UTC".format(strStartDate, strEndDate))
2702        uLogger.debug("Calculated history length: [{}], interval: [{}]".format(length, interval))
2703        uLogger.debug("Data blocks, count: [{}], max candles in block: [{}]".format(blocks, TKS_CANDLE_INTERVALS[interval][2]))
2704        uLogger.debug("Requesting history candlesticks, ticker: [{}], FIGI: [{}]. Wait, please...".format(self.ticker, self.figi))
2705
2706        tempOld = None  # pandas object for old history, if --only-missing key present
2707        lastTime = None  # datetime object of last old candle in file
2708
2709        if onlyMissing and self.historyFile is not None and self.historyFile and os.path.exists(self.historyFile):
2710            uLogger.debug("--only-missing key present, add only last missing candles...")
2711            uLogger.debug("History file will be updated: [{}]".format(os.path.abspath(self.historyFile)))
2712
2713            tempOld = pd.read_csv(self.historyFile, sep=csvSep, header=None, names=headers)
2714
2715            tempOld["date"] = pd.to_datetime(tempOld["date"])  # load date "as is"
2716            tempOld["date"] = tempOld["date"].dt.strftime("%Y.%m.%d")  # convert date to string
2717            tempOld["time"] = pd.to_datetime(tempOld["time"])  # load time "as is"
2718            tempOld["time"] = tempOld["time"].dt.strftime("%H:%M")  # convert time to string
2719
2720            # get last datetime object from last string in file or minus 1 delta if file is empty:
2721            if len(tempOld) > 0:
2722                lastTime = datetime.strptime(tempOld.date.iloc[-1] + " " + tempOld.time.iloc[-1], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2723
2724            else:
2725                lastTime = dtEnd - timedelta(days=1)  # history file is empty, so last date set at -1 day
2726
2727            tempOld = tempOld[:-1]  # always remove last old candle because it may be incompletely at the current time
2728
2729        responseJSONs = []  # raw history blocks of data
2730
2731        blockEnd = dtEnd
2732        for item in range(blocks):
2733            tail = length % TKS_CANDLE_INTERVALS[interval][2] if item + 1 == blocks else TKS_CANDLE_INTERVALS[interval][2]
2734            blockStart = blockEnd - timedelta(minutes=TKS_CANDLE_INTERVALS[interval][1] * tail)
2735
2736            uLogger.debug("[Block #{}/{}] time period: [{}] UTC - [{}] UTC".format(
2737                item + 1, blocks, blockStart.strftime(TKS_DATE_TIME_FORMAT), blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2738            ))
2739
2740            if blockStart == blockEnd:
2741                uLogger.debug("Skipped this zero-length block...")
2742
2743            else:
2744                # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetCandles
2745                historyURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetCandles"
2746                self.body = str({
2747                    "figi": self.figi,
2748                    "from": blockStart.strftime(TKS_DATE_TIME_FORMAT),
2749                    "to": blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2750                    "interval": TKS_CANDLE_INTERVALS[interval][0]
2751                })
2752                responseJSON = self.SendAPIRequest(historyURL, reqType="POST", retry=1, pause=1)
2753
2754                if "code" in responseJSON.keys():
2755                    uLogger.debug("An issue occurred and block #{}/{} is empty".format(item + 1, blocks))
2756
2757                else:
2758                    if start is not None and (start.lower() == "yesterday" or start == end) and interval == "day" and len(responseJSON["candles"]) > 1:
2759                        responseJSON["candles"] = responseJSON["candles"][:-1]  # removes last candle for "yesterday" request
2760
2761                    responseJSONs = responseJSON["candles"] + responseJSONs  # add more old history behind newest dates
2762
2763            blockEnd = blockStart
2764
2765        printCount = len(responseJSONs)  # candles to show in console
2766        if responseJSONs:
2767            tempHistory = pd.DataFrame(
2768                data={
2769                    "date": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2770                    "time": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2771                    "open": [NanoToFloat(item["open"]["units"], item["open"]["nano"]) for item in responseJSONs],
2772                    "high": [NanoToFloat(item["high"]["units"], item["high"]["nano"]) for item in responseJSONs],
2773                    "low": [NanoToFloat(item["low"]["units"], item["low"]["nano"]) for item in responseJSONs],
2774                    "close": [NanoToFloat(item["close"]["units"], item["close"]["nano"]) for item in responseJSONs],
2775                    "volume": [int(item["volume"]) for item in responseJSONs],
2776                },
2777                index=range(len(responseJSONs)),
2778                columns=["date", "time", "open", "high", "low", "close", "volume"],
2779            )
2780            tempHistory["date"] = tempHistory["date"].dt.strftime("%Y.%m.%d")
2781            tempHistory["time"] = tempHistory["time"].dt.strftime("%H:%M")
2782
2783            # append only newest candles to old history if --only-missing key present:
2784            if onlyMissing and tempOld is not None and lastTime is not None:
2785                index = 0  # find start index in tempHistory data:
2786
2787                for i, item in tempHistory.iterrows():
2788                    curTime = datetime.strptime(item["date"] + " " + item["time"], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2789
2790                    if curTime == lastTime:
2791                        uLogger.debug("History will be updated starting from the date: [{}]".format(curTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
2792                        index = i
2793                        printCount = index + 1
2794                        break
2795
2796                history = pd.concat([tempOld, tempHistory[index:]], ignore_index=True)
2797
2798            else:
2799                history = tempHistory  # if no `--only-missing` key then load full data from server
2800
2801            uLogger.debug("Last 3 rows of received history:\n{}".format(pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-3:], max_cols=20, index=False)))
2802
2803        if history is not None and not history.empty:
2804            if show:
2805                uLogger.info("Here's requested history between [{}] UTC and [{}] UTC, not-empty candles count: [{}]\n{}".format(
2806                    strStartDate.replace("T", " ").replace("Z", ""), strEndDate.replace("T", " ").replace("Z", ""), len(history[-printCount:]),
2807                    pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-printCount:], max_cols=20, index=False),
2808                ))
2809
2810        else:
2811            uLogger.warning("Received an empty candles history!")
2812
2813        if self.historyFile is not None:
2814            if history is not None and not history.empty:
2815                history.to_csv(self.historyFile, sep=csvSep, index=False, header=None)
2816                uLogger.info("Ticker [{}], FIGI [{}], tf: [{}], history saved: [{}]".format(self.ticker, self.figi, interval, os.path.abspath(self.historyFile)))
2817
2818            else:
2819                uLogger.warning("Empty history received! File NOT updated: [{}]".format(os.path.abspath(self.historyFile)))
2820
2821        else:
2822            uLogger.debug("--output key is not defined. Parsed history file not saved to file, only Pandas DataFrame returns.")
2823
2824        return history
2825
2826    def LoadHistory(self, filePath: str) -> pd.DataFrame:
2827        """
2828        Load candles history from csv-file and return Pandas DataFrame object.
2829
2830        See also: `History()` and `ShowHistoryChart()` methods.
2831
2832        :param filePath: path to csv-file to open.
2833        """
2834        loadedHistory = None  # init candles data object
2835
2836        uLogger.debug("Loading candles history with PriceGenerator module. Wait, please...")
2837
2838        if os.path.exists(filePath):
2839            loadedHistory = self.priceModel.LoadFromFile(filePath)  # load data and get chain of candles as Pandas DataFrame
2840
2841            tfStr = self.priceModel.FormattedDelta(
2842                self.priceModel.timeframe,
2843                "{days} days {hours}h {minutes}m {seconds}s",
2844            ) if self.priceModel.timeframe >= timedelta(days=1) else self.priceModel.FormattedDelta(
2845                self.priceModel.timeframe,
2846                "{hours}h {minutes}m {seconds}s",
2847            )
2848
2849            if loadedHistory is not None and not loadedHistory.empty:
2850                uLogger.info("Rows count loaded: [{}], detected timeframe of candles: [{}]. Showing some last rows:\n{}".format(
2851                    len(loadedHistory),
2852                    tfStr,
2853                    pd.DataFrame.to_string(loadedHistory[-10:], max_cols=20)),
2854                )
2855
2856            else:
2857                uLogger.warning("It was loaded an empty history! Path: [{}]".format(os.path.abspath(filePath)))
2858
2859        else:
2860            uLogger.error("File with candles history does not exist! Check the path: [{}]".format(filePath))
2861
2862        return loadedHistory
2863
2864    def ShowHistoryChart(self, candles: Union[str, pd.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:
2865        """
2866        Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.
2867
2868        Self variable `htmlHistoryFile` can be use as html-file name to save interaction or non-interaction chart.
2869        Default: `index.html` (both for interact and non-interact candlesticks chart).
2870
2871        See also: `History()` and `LoadHistory()` methods.
2872
2873        :param candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
2874        :param interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart.
2875                         See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters
2876                         If False then chain of candlesticks will render as not interactive Google Candlestick chart.
2877                         See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
2878        :param openInBrowser: if True then immediately open chart in default browser, otherwise only path to
2879                              html-file prints to console. False by default, to avoid issues with `permissions denied` to html-file.
2880        """
2881        if isinstance(candles, str):
2882            self.priceModel.prices = self.LoadHistory(filePath=candles)  # load candles chain from file
2883            self.priceModel.ticker = os.path.basename(candles)  # use filename as ticker name in PriceGenerator
2884
2885        elif isinstance(candles, pd.DataFrame):
2886            self.priceModel.prices = candles  # set candles chain from variable
2887            self.priceModel.ticker = self.ticker  # use current TKSBrokerAPI ticker as ticker name in PriceGenerator
2888
2889            if "datetime" not in candles.columns:
2890                self.priceModel.prices["datetime"] = pd.to_datetime(candles.date + ' ' + candles.time, utc=True)  # PriceGenerator uses "datetime" column with date and time
2891
2892        else:
2893            uLogger.error("`candles` variable must be path string to the csv-file with candles in OHLCV-model or like Pandas Dataframe object!")
2894            raise Exception("Incorrect value")
2895
2896        self.priceModel.horizon = len(self.priceModel.prices)  # use length of candles data as horizon in PriceGenerator
2897
2898        if interact:
2899            uLogger.debug("Rendering interactive candles chart. Wait, please...")
2900
2901            self.priceModel.RenderBokeh(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2902
2903        else:
2904            uLogger.debug("Rendering non-interactive candles chart. Wait, please...")
2905
2906            self.priceModel.RenderGoogle(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2907
2908        uLogger.info("Rendered candles chart: [{}]".format(os.path.abspath(self.htmlHistoryFile)))
2909
2910    def Trade(self, operation: str, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2911        """
2912        Universal method to create market order and make deal at the current price for current `accountId`. Returns JSON data with response.
2913        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2914
2915        See also: `Order()` docstring. More simple methods than `Trade()` are `Buy()` and `Sell()`.
2916
2917        :param operation: string "Buy" or "Sell".
2918        :param lots: volume, integer count of lots >= 1.
2919        :param tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter `targetPrice` in `self.Order()`.
2920        :param sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter `targetPrice` in `self.Order()`.
2921        :param expDate: string "Undefined" by default or local date in future,
2922                        it is a string with format `%Y-%m-%d %H:%M:%S`.
2923        :return: JSON with response from broker server.
2924        """
2925        if self.accountId is None or not self.accountId:
2926            uLogger.error("Variable `accountId` must be defined for using this method!")
2927            raise Exception("Account ID required")
2928
2929        if operation is None or not operation or operation not in ("Buy", "Sell"):
2930            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
2931            raise Exception("Incorrect value")
2932
2933        if lots is None or lots < 1:
2934            uLogger.warning("You must define trade volume > 0: integer count of lots! For current operation lots reset to 1.")
2935            lots = 1
2936
2937        if tp is None or tp < 0:
2938            tp = 0
2939
2940        if sl is None or sl < 0:
2941            sl = 0
2942
2943        if expDate is None or not expDate:
2944            expDate = "Undefined"
2945
2946        if not (self.ticker or self.figi):
2947            uLogger.error("Ticker or FIGI must be defined!")
2948            raise Exception("Ticker or FIGI required")
2949
2950        instrument = self.SearchByTicker(requestPrice=True) if self.ticker else self.SearchByFIGI(requestPrice=True)
2951        self.ticker = instrument["ticker"]
2952        self.figi = instrument["figi"]
2953
2954        uLogger.debug("Opening [{}] market order: ticker [{}], FIGI [{}], lots [{}], TP [{:.4f}], SL [{:.4f}], expiration date of TP/SL orders [{}]. Wait, please...".format(operation, self.ticker, self.figi, lots, tp, sl, expDate))
2955
2956        openTradeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
2957        self.body = str({
2958            "figi": self.figi,
2959            "quantity": str(lots),
2960            "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
2961            "accountId": str(self.accountId),
2962            "orderType": "ORDER_TYPE_MARKET",  # see: TKS_ORDER_TYPES
2963        })
2964        response = self.SendAPIRequest(openTradeURL, reqType="POST", retry=0)
2965
2966        if "orderId" in response.keys():
2967            uLogger.info("[{}] market order [{}] was executed: ticker [{}], FIGI [{}], lots [{}]. Total order price: [{:.4f} {}] (with commission: [{:.2f} {}]). Average price of lot: [{:.2f} {}]".format(
2968                operation, response["orderId"],
2969                self.ticker, self.figi, lots,
2970                NanoToFloat(response["totalOrderAmount"]["units"], response["totalOrderAmount"]["nano"]), response["totalOrderAmount"]["currency"],
2971                NanoToFloat(response["initialCommission"]["units"], response["initialCommission"]["nano"]), response["initialCommission"]["currency"],
2972                NanoToFloat(response["executedOrderPrice"]["units"], response["executedOrderPrice"]["nano"]), response["executedOrderPrice"]["currency"],
2973            ))
2974
2975            if tp > 0:
2976                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=tp, limitPrice=tp, stopType="TP", expDate=expDate)
2977
2978            if sl > 0:
2979                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=sl, limitPrice=sl, stopType="SL", expDate=expDate)
2980
2981        else:
2982            uLogger.warning("Not `oK` status received! Market order not executed. See full debug log or try again and open order later.")
2983
2984        return response
2985
2986    def Buy(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2987        """
2988        More simple method than `Trade()`. Create `Buy` market order and make deal at the current price. Returns JSON data with response.
2989        If `tp` or `sl` > 0, then in additional will opens stop-orders with "TP" and "SL" flags for `stopType` parameter.
2990
2991        See also: `Order()` and `Trade()` docstrings.
2992
2993        :param lots: volume, integer count of lots >= 1.
2994        :param tp: float > 0, take profit price of stop-order.
2995        :param sl: float > 0, stop loss price of stop-order.
2996        :param expDate: it's a local date in future.
2997                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
2998        :return: JSON with response from broker server.
2999        """
3000        return self.Trade(operation="Buy", lots=lots, tp=tp, sl=sl, expDate=expDate)
3001
3002    def Sell(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3003        """
3004        More simple method than `Trade()`. Create `Sell` market order and make deal at the current price. Returns JSON data with response.
3005        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
3006
3007        See also: `Order()` and `Trade()` docstrings.
3008
3009        :param lots: volume, integer count of lots >= 1.
3010        :param tp: float > 0, take profit price of stop-order.
3011        :param sl: float > 0, stop loss price of stop-order.
3012        :param expDate: it's a local date in the future.
3013                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3014        :return: JSON with response from broker server.
3015        """
3016        return self.Trade(operation="Sell", lots=lots, tp=tp, sl=sl, expDate=expDate)
3017
3018    def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:
3019        """
3020        Close position of given instruments.
3021
3022        :param instruments: list of instruments defined by tickers or FIGIs that must be closed.
3023        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3024                         This avoids unnecessary downloading data from the server.
3025        """
3026        if instruments is None or not instruments:
3027            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3028            raise Exception("Ticker or FIGI required")
3029
3030        if isinstance(instruments, str):
3031            instruments = [instruments]
3032
3033        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3034        if uniqueInstruments:
3035            if portfolio is None or not portfolio:
3036                portfolio = self.Overview(show=False)
3037
3038            allOpened = [item["figi"] for iType in TKS_INSTRUMENTS for item in portfolio["stat"][iType]]
3039            uLogger.debug("All opened instruments by it's FIGI: {}".format(", ".join(allOpened)))
3040
3041            for self.figi in uniqueInstruments:
3042                if self.figi not in allOpened:
3043                    uLogger.warning("Instrument with FIGI [{}] not in open positions list!".format(self.figi))
3044                    continue
3045
3046                # search open trade info about instrument by ticker:
3047                instrument = {}
3048                for iType in TKS_INSTRUMENTS:
3049                    if instrument:
3050                        break
3051
3052                    for item in portfolio["stat"][iType]:
3053                        if item["figi"] == self.figi:
3054                            instrument = item
3055                            break
3056
3057                if instrument:
3058                    self.ticker = instrument["ticker"]
3059                    self.figi = instrument["figi"]
3060
3061                    uLogger.debug("Closing trade of instrument: ticker [{}], FIGI[{}], lots [{}]{}. Wait, please...".format(
3062                        self.ticker,
3063                        self.figi,
3064                        int(instrument["volume"]),
3065                        ", blocked [{}]".format(instrument["blocked"]) if instrument["blocked"] > 0 else "",
3066                    ))
3067
3068                    tradeLots = abs(instrument["lots"]) - instrument["blocked"]  # available volumes in lots for close operation
3069
3070                    if tradeLots > 0:
3071                        if instrument["blocked"] > 0:
3072                            uLogger.warning("Just for your information: there are [{}] lots blocked for instrument [{}]! Available only [{}] lots to closing trade.".format(
3073                                instrument["blocked"],
3074                                self.ticker,
3075                                tradeLots,
3076                            ))
3077
3078                        # if direction is "Long" then we need sell, if direction is "Short" then we need buy:
3079                        self.Trade(operation="Sell" if instrument["direction"] == "Long" else "Buy", lots=tradeLots)
3080
3081                    else:
3082                        uLogger.warning("There are no available lots for instrument [{}] to closing trade at this moment! Try again later or cancel some orders.".format(self.ticker))
3083
3084    def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:
3085        """
3086        Close all positions of given instruments with defined type.
3087
3088        :param iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
3089        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3090                         This avoids unnecessary downloading data from the server.
3091        """
3092        if iType not in TKS_INSTRUMENTS:
3093            uLogger.warning("Type of the instrument must be one of supported types: {}. Given: [{}]".format(", ".join(TKS_INSTRUMENTS), iType))
3094
3095        else:
3096            if portfolio is None or not portfolio:
3097                portfolio = self.Overview(show=False)
3098
3099            tickers = [item["ticker"] for item in portfolio["stat"][iType]]
3100            uLogger.debug("Instrument tickers with type [{}] that will be closed: {}".format(iType, tickers))
3101
3102            if tickers and portfolio:
3103                self.CloseTrades(tickers, portfolio)
3104
3105            else:
3106                uLogger.info("Instrument tickers with type [{}] not found, nothing to close.".format(iType))
3107
3108    def Order(self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3109        """
3110        Universal method to create market or limit orders with all available parameters for current `accountId`.
3111        See more simple methods: `BuyLimit()`, `BuyStop()`, `SellLimit()`, `SellStop()`.
3112
3113        If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above
3114        current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.
3115
3116        Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell"
3117        then broker immediately open market order as you can do simple --buy or --sell operations!
3118
3119        If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell".
3120        When current price will go up or down to target price value then broker opens a limit order.
3121        Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.
3122
3123        Only one attempt and no retry for opens order. If network issue occurred you can create new request.
3124
3125        :param operation: string "Buy" or "Sell".
3126        :param orderType: string "Limit" or "Stop".
3127        :param lots: volume, integer count of lots >= 1.
3128        :param targetPrice: target price > 0. This is open trade price for limit order.
3129        :param limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice.
3130                           Broker will creates limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
3131        :param stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types
3132                         "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3133                         Stop loss order always executed by market price.
3134        :param expDate: string "Undefined" by default or local date in future.
3135                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3136                        This date is converting to UTC format for server. This parameter only makes sense for stop-order.
3137                        A limit order has no expiration date, it lasts until the end of the trading day.
3138        :return: JSON with response from broker server.
3139        """
3140        if self.accountId is None or not self.accountId:
3141            uLogger.error("Variable `accountId` must be defined for using this method!")
3142            raise Exception("Account ID required")
3143
3144        if operation is None or not operation or operation not in ("Buy", "Sell"):
3145            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3146            raise Exception("Incorrect value")
3147
3148        if orderType is None or not orderType or orderType not in ("Limit", "Stop"):
3149            uLogger.error("You must define order type only one of them: `Limit` or `Stop`!")
3150            raise Exception("Incorrect value")
3151
3152        if lots is None or lots < 1:
3153            uLogger.error("You must define trade volume > 0: integer count of lots!")
3154            raise Exception("Incorrect value")
3155
3156        if targetPrice is None or targetPrice <= 0:
3157            uLogger.error("Target price for limit-order must be greater than 0!")
3158            raise Exception("Incorrect value")
3159
3160        if limitPrice is None or limitPrice <= 0:
3161            limitPrice = targetPrice
3162
3163        if stopType is None or not stopType or stopType not in ("SL", "TP", "Limit"):
3164            stopType = "Limit"
3165
3166        if expDate is None or not expDate:
3167            expDate = "Undefined"
3168
3169        if not (self.ticker or self.figi):
3170            uLogger.error("Tocker or FIGI must be defined!")
3171            raise Exception("Ticker or FIGI required")
3172
3173        response = {}
3174        instrument = self.SearchByTicker(requestPrice=True) if self.ticker else self.SearchByFIGI(requestPrice=True)
3175        self.ticker = instrument["ticker"]
3176        self.figi = instrument["figi"]
3177
3178        if orderType == "Limit":
3179            uLogger.debug(
3180                "Creating pending limit-order: ticker [{}], FIGI [{}], action [{}], lots [{}] and the target price [{:.2f} {}]. Wait, please...".format(
3181                    self.ticker, self.figi,
3182                    operation, lots, targetPrice, instrument["currency"],
3183                ))
3184
3185            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3186            self.body = str({
3187                "figi": self.figi,
3188                "quantity": str(lots),
3189                "price": FloatToNano(targetPrice),
3190                "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3191                "accountId": str(self.accountId),
3192                "orderType": "ORDER_TYPE_LIMIT",  # see: TKS_ORDER_TYPES
3193            })
3194            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3195
3196            if "orderId" in response.keys():
3197                uLogger.info(
3198                    "Limit-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}]".format(
3199                        response["orderId"],
3200                        self.ticker, self.figi,
3201                        operation, lots, targetPrice, instrument["currency"],
3202                    ))
3203
3204                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3205                    if operation == "Buy" and targetPrice > instrument["currentPrice"]["lastPrice"]:
3206                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was higher than current price [{:.2f} {}] broker immediately opened `Buy` market order, such as if you did simple `--buy` operation.".format(
3207                            targetPrice, instrument["currency"],
3208                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3209                        ))
3210
3211                    if operation == "Sell" and targetPrice < instrument["currentPrice"]["lastPrice"]:
3212                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was lower than current price [{:.2f} {}] broker immediately opened `Sell` market order, such as if you did simple `--sell` operation.".format(
3213                            targetPrice, instrument["currency"],
3214                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3215                        ))
3216
3217            else:
3218                uLogger.warning("Not `oK` status received! Limit order not opened. See full debug log or try again and open order later.")
3219
3220        if orderType == "Stop":
3221            uLogger.debug(
3222                "Creating stop-order: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and local expiration date [{}]. Wait, please...".format(
3223                    self.ticker, self.figi,
3224                    operation, lots,
3225                    targetPrice, instrument["currency"],
3226                    limitPrice, instrument["currency"],
3227                    stopType, expDate,
3228                ))
3229
3230            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/PostStopOrder"
3231            expDateUTC = "" if expDate == "Undefined" else datetime.strptime(expDate, TKS_PRINT_DATE_TIME_FORMAT).replace(tzinfo=tzlocal()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT_EXT)
3232            stopOrderType = "STOP_ORDER_TYPE_STOP_LOSS" if stopType == "SL" else "STOP_ORDER_TYPE_TAKE_PROFIT" if stopType == "TP" else "STOP_ORDER_TYPE_STOP_LIMIT"
3233
3234            body = {
3235                "figi": self.figi,
3236                "quantity": str(lots),
3237                "price": FloatToNano(limitPrice),
3238                "stopPrice": FloatToNano(targetPrice),
3239                "direction": "STOP_ORDER_DIRECTION_BUY" if operation == "Buy" else "STOP_ORDER_DIRECTION_SELL",  # see: TKS_STOP_ORDER_DIRECTIONS
3240                "accountId": str(self.accountId),
3241                "expirationType": "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE" if expDateUTC else "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL",  # see: TKS_STOP_ORDER_EXPIRATION_TYPES
3242                "stopOrderType": stopOrderType,  # see: TKS_STOP_ORDER_TYPES
3243            }
3244
3245            if expDateUTC:
3246                body["expireDate"] = expDateUTC
3247
3248            self.body = str(body)
3249            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3250
3251            if "stopOrderId" in response.keys():
3252                uLogger.info(
3253                    "Stop-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and expiration date in UTC [{}]".format(
3254                        response["stopOrderId"],
3255                        self.ticker, self.figi,
3256                        operation, lots,
3257                        targetPrice, instrument["currency"],
3258                        limitPrice, instrument["currency"],
3259                        TKS_STOP_ORDER_TYPES[stopOrderType],
3260                        datetime.strptime(expDateUTC, TKS_DATE_TIME_FORMAT_EXT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if expDateUTC else TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"],
3261                    ))
3262
3263                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3264                    if operation == "Buy" and targetPrice < instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3265                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target buy price [{:.2f} {}] is lower than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3266                            targetPrice, instrument["currency"],
3267                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3268                        ))
3269
3270                    if operation == "Sell" and targetPrice > instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3271                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target sell price [{:.2f} {}] is higher than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3272                            targetPrice, instrument["currency"],
3273                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3274                        ))
3275
3276            else:
3277                uLogger.warning("Not `oK` status received! Stop order not opened. See full debug log or try again and open order later.")
3278
3279        return response
3280
3281    def BuyLimit(self, lots: int, targetPrice: float) -> dict:
3282        """
3283        Create pending `Buy` limit-order (below current price). You must specify only 2 parameters:
3284        `lots` and `target price` to open buy limit-order. If you try to create buy limit-order above current price then
3285        broker immediately open `Buy` market order, such as if you do simple `--buy` operation!
3286        See also: `Order()` docstring.
3287
3288        :param lots: volume, integer count of lots >= 1.
3289        :param targetPrice: target price > 0. This is open trade price for limit order.
3290        :return: JSON with response from broker server.
3291        """
3292        return self.Order(operation="Buy", orderType="Limit", lots=lots, targetPrice=targetPrice)
3293
3294    def BuyStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3295        """
3296        Create `Buy` stop-order. You must specify at least 2 parameters: `lots` `target price` to open buy stop-order.
3297        In additional you can specify 3 parameters for buy stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3298        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3299        target price value then broker opens a limit order. See also: `Order()` docstring.
3300
3301        :param lots: volume, integer count of lots >= 1.
3302        :param targetPrice: target price > 0. This is trigger price for buy stop-order.
3303        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3304                           with price equal to limitPrice, when current price goes to target price of buy stop-order.
3305        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3306                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3307        :param expDate: string "Undefined" by default or local date in future.
3308                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3309                        This date is converting to UTC format for server.
3310        :return: JSON with response from broker server.
3311        """
3312        return self.Order(operation="Buy", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3313
3314    def SellLimit(self, lots: int, targetPrice: float) -> dict:
3315        """
3316        Create pending `Sell` limit-order (above current price). You must specify only 2 parameters:
3317        `lots` and `target price` to open sell limit-order. If you try to create sell limit-order below current price then
3318        broker immediately open `Sell` market order, such as if you do simple `--sell` operation!
3319        See also: `Order()` docstring.
3320
3321        :param lots: volume, integer count of lots >= 1.
3322        :param targetPrice: target price > 0. This is open trade price for limit order.
3323        :return: JSON with response from broker server.
3324        """
3325        return self.Order(operation="Sell", orderType="Limit", lots=lots, targetPrice=targetPrice)
3326
3327    def SellStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3328        """
3329        Create `Sell` stop-order. You must specify at least 2 parameters: `lots` `target price` to open sell stop-order.
3330        In additional you can specify 3 parameters for sell stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3331        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3332        target price value then broker opens a limit order. See also: `Order()` docstring.
3333
3334        :param lots: volume, integer count of lots >= 1.
3335        :param targetPrice: target price > 0. This is trigger price for sell stop-order.
3336        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3337                           with price equal to limitPrice, when current price goes to target price of sell stop-order.
3338        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3339                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3340        :param expDate: string "Undefined" by default or local date in future.
3341                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3342                        This date is converting to UTC format for server.
3343        :return: JSON with response from broker server.
3344        """
3345        return self.Order(operation="Sell", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3346
3347    def CloseOrders(self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:
3348        """
3349        Cancel order or list of orders by its `orderId` or `stopOrderId` for current `accountId`.
3350
3351        :param orderIDs: list of integers with `orderId` or `stopOrderId`.
3352        :param allOrdersIDs: pre-received lists of all active pending orders.
3353                             This avoids unnecessary downloading data from the server.
3354        :param allStopOrdersIDs: pre-received lists of all active stop orders.
3355        """
3356        if self.accountId is None or not self.accountId:
3357            uLogger.error("Variable `accountId` must be defined for using this method!")
3358            raise Exception("Account ID required")
3359
3360        if orderIDs:
3361            if allOrdersIDs is None or not allOrdersIDs:
3362                rawOrders = self.RequestPendingOrders()
3363                allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending orders ID
3364
3365            if allStopOrdersIDs is None or not allStopOrdersIDs:
3366                rawStopOrders = self.RequestStopOrders()
3367                allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3368
3369            for orderID in orderIDs:
3370                idInPendingOrders = orderID in allOrdersIDs
3371                idInStopOrders = orderID in allStopOrdersIDs
3372
3373                if not (idInPendingOrders or idInStopOrders):
3374                    uLogger.warning("Order not found by ID: [{}]. Maybe cancelled already? Check it with `--overview` key.".format(orderID))
3375                    continue
3376
3377                else:
3378                    if idInPendingOrders:
3379                        uLogger.debug("Cancelling pending order with ID: [{}]. Wait, please...".format(orderID))
3380
3381                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_CancelOrder
3382                        self.body = str({"accountId": self.accountId, "orderId": orderID})
3383                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/CancelOrder"
3384                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3385
3386                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3387                            if self.moreDebug:
3388                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3389
3390                            uLogger.info("Pending order with ID [{}] successfully cancel".format(orderID))
3391
3392                        else:
3393                            uLogger.warning("Unknown issue occurred when cancelling pending order with ID: [{}]. Check ID and try again.".format(orderID))
3394
3395                    elif idInStopOrders:
3396                        uLogger.debug("Cancelling stop order with ID: [{}]. Wait, please...".format(orderID))
3397
3398                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_CancelStopOrder
3399                        self.body = str({"accountId": self.accountId, "stopOrderId": orderID})
3400                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/CancelStopOrder"
3401                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3402
3403                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3404                            if self.moreDebug:
3405                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3406
3407                            uLogger.info("Stop order with ID [{}] successfully cancel".format(orderID))
3408
3409                        else:
3410                            uLogger.warning("Unknown issue occurred when cancelling stop order with ID: [{}]. Check ID and try again.".format(orderID))
3411
3412                    else:
3413                        continue
3414
3415    def CloseAllOrders(self) -> None:
3416        """
3417        Gets a list of open pending and stop orders and cancel it all.
3418        """
3419        rawOrders = self.RequestPendingOrders()
3420        allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending orders ID
3421        lenOrders = len(allOrdersIDs)
3422
3423        rawStopOrders = self.RequestStopOrders()
3424        allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3425        lenSOrders = len(allStopOrdersIDs)
3426
3427        if lenOrders > 0 or lenSOrders > 0:
3428            uLogger.info("Found: [{}] opened pending and [{}] stop orders. Let's trying to cancel it all. Wait, please...".format(lenOrders, lenSOrders))
3429
3430            self.CloseOrders(allOrdersIDs + allStopOrdersIDs, allOrdersIDs, allStopOrdersIDs)
3431
3432        else:
3433            uLogger.info("Orders not found, nothing to cancel.")
3434
3435    def CloseAll(self, *args) -> None:
3436        """
3437        Close all available (not blocked) opened trades and orders.
3438
3439        Also, you can select one or more keywords case-insensitive:
3440        `orders`, `shares`, `bonds`, `etfs` and `futures` from `TKS_INSTRUMENTS` enum to specify trades type.
3441
3442        Currency positions you must close manually using buy or sell operations, `CloseTrades()` or `CloseAllTrades()` methods.
3443        """
3444        overview = self.Overview(show=False)  # get all open trades info
3445
3446        if len(args) == 0:
3447            uLogger.debug("Closing all available (not blocked) opened trades and orders. Currency positions you must closes manually using buy or sell operations! Wait, please...")
3448            self.CloseAllOrders()  # close all pending and stop orders
3449
3450            for iType in TKS_INSTRUMENTS:
3451                if iType != "Currencies":
3452                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3453
3454        else:
3455            uLogger.debug("Closing all available {}. Currency positions you must closes manually using buy or sell operations! Wait, please...".format(list(args)))
3456            lowerArgs = [x.lower() for x in args]
3457
3458            if "orders" in lowerArgs:
3459                self.CloseAllOrders()  # close all pending and stop orders
3460
3461            for iType in TKS_INSTRUMENTS:
3462                if iType.lower() in lowerArgs and iType != "Currencies":
3463                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3464
3465    @staticmethod
3466    def ParseOrderParameters(operation, **inputParameters):
3467        """
3468        Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.
3469
3470        :param operation: string "Buy" or "Sell".
3471        :param inputParameters: this is dict of strings that looks like this
3472               `{"lots": "L_int,...", "prices": "P_float,..."}` where
3473               "lots" key: one or more lot values (integer numbers) to open with every limit-order
3474               "prices" key: one or more prices to open limit-orders
3475               Counts of values in lots and prices lists must be equals!
3476        :return: list of dictionaries with all lots and prices to open orders that looks like this `[{"lot": lots_1, "price": price_1}, {...}, ...]`
3477        """
3478        # TODO: update order grid work with api v2
3479        pass
3480        # uLogger.debug("Input parameters: {}".format(inputParameters))
3481        #
3482        # if operation is None or not operation or operation not in ("Buy", "Sell"):
3483        #     uLogger.error("You must define operation type: 'Buy' or 'Sell'!")
3484        #     raise Exception("Incorrect value")
3485        #
3486        # if "l" in inputParameters.keys():
3487        #     inputParameters["lots"] = inputParameters.pop("l")
3488        #
3489        # if "p" in inputParameters.keys():
3490        #     inputParameters["prices"] = inputParameters.pop("p")
3491        #
3492        # if "lots" not in inputParameters.keys() or "prices" not in inputParameters.keys():
3493        #     uLogger.error("Both of 'lots' and 'prices' keys must be define to open grid orders!")
3494        #     raise Exception("Incorrect value")
3495        #
3496        # lots = [int(item.strip()) for item in inputParameters["lots"].split(",")]
3497        # prices = [float(item.strip()) for item in inputParameters["prices"].split(",")]
3498        #
3499        # if len(lots) != len(prices):
3500        #     uLogger.error("'lots' and 'prices' lists must have equal length of values!")
3501        #     raise Exception("Incorrect value")
3502        #
3503        # uLogger.debug("Extracted parameters for orders:")
3504        # uLogger.debug("lots = {}".format(lots))
3505        # uLogger.debug("prices = {}".format(prices))
3506        #
3507        # # list of dictionaries with order's parameters: [{"lot": lots_1, "price": price_1}, {...}, ...]
3508        # result = [{"lot": lots[item], "price": prices[item]} for item in range(len(prices))]
3509        # uLogger.debug("Order parameters: {}".format(result))
3510        #
3511        # return result
3512
3513    def IsInPortfolio(self, portfolio: dict = None) -> bool:
3514        """
3515        Checks if instrument is in the user's portfolio. Instrument must be defined by `ticker` (highly priority) or `figi`.
3516
3517        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3518        :return: `True` if portfolio contains open position with given instrument, `False` otherwise.
3519        """
3520        result = False
3521        msg = "Instrument not defined!"
3522
3523        if portfolio is None or not portfolio:
3524            portfolio = self.Overview(show=False)
3525
3526        if self.ticker:
3527            uLogger.debug("Searching instrument with ticker [{}] throwout opened positions...".format(self.ticker))
3528            msg = "Instrument with ticker [{}] is not present in open positions".format(self.ticker)
3529
3530            for iType in TKS_INSTRUMENTS:
3531                for instrument in portfolio["stat"][iType]:
3532                    if instrument["ticker"] == self.ticker:
3533                        result = True
3534                        msg = "Instrument with ticker [{}] is present in open positions".format(self.ticker)
3535                        break
3536
3537        elif self.figi:
3538            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self.figi))
3539            msg = "Instrument with FIGI [{}] is not present in open positions".format(self.figi)
3540
3541            for iType in TKS_INSTRUMENTS:
3542                for instrument in portfolio["stat"][iType]:
3543                    if instrument["figi"] == self.figi:
3544                        result = True
3545                        msg = "Instrument with FIGI [{}] is present in open positions".format(self.figi)
3546                        break
3547
3548        else:
3549            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3550
3551        uLogger.debug(msg)
3552
3553        return result
3554
3555    def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:
3556        """
3557        Returns instrument is in the user's portfolio if it presents there.
3558        Instrument must be defined by `ticker` (highly priority) or `figi`.
3559
3560        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3561        :return: dict with instrument if portfolio contains open position with this instrument, `None` otherwise.
3562        """
3563        result = None
3564        msg = "Instrument not defined!"
3565
3566        if portfolio is None or not portfolio:
3567            portfolio = self.Overview(show=False)
3568
3569        if self.ticker:
3570            uLogger.debug("Searching instrument with ticker [{}] throwout opened positions...".format(self.ticker))
3571            msg = "Instrument with ticker [{}] is not present in open positions".format(self.ticker)
3572
3573            for iType in TKS_INSTRUMENTS:
3574                for instrument in portfolio["stat"][iType]:
3575                    if instrument["ticker"] == self.ticker:
3576                        result = instrument
3577                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(self.ticker, instrument["figi"])
3578                        break
3579
3580        elif self.figi:
3581            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self.figi))
3582            msg = "Instrument with FIGI [{}] is not present in open positions".format(self.figi)
3583
3584            for iType in TKS_INSTRUMENTS:
3585                for instrument in portfolio["stat"][iType]:
3586                    if instrument["figi"] == self.figi:
3587                        result = instrument
3588                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(instrument["ticker"], self.figi)
3589                        break
3590
3591        else:
3592            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3593
3594        uLogger.debug(msg)
3595
3596        return result
3597
3598    def RequestLimits(self) -> dict:
3599        """
3600        Method for obtaining the available funds for withdrawal for current `accountId`.
3601
3602        See also:
3603        - REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
3604        - `OverviewLimits()` method
3605
3606        :return: dict with raw data from server that contains free funds for withdrawal. Example of dict:
3607                 `{"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}`.
3608                 Here `money` is an array of portfolio currency positions, `blocked` is an array of blocked currency
3609                 positions of the portfolio and `blockedGuarantee` is locked money under collateral for futures.
3610        """
3611        if self.accountId is None or not self.accountId:
3612            uLogger.error("Variable `accountId` must be defined for using this method!")
3613            raise Exception("Account ID required")
3614
3615        uLogger.debug("Requesting current available funds for withdrawal. Wait, please...")
3616
3617        self.body = str({"accountId": self.accountId})
3618        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetWithdrawLimits"
3619        rawLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3620
3621        if self.moreDebug:
3622            uLogger.debug("Records about available funds for withdrawal successfully received")
3623
3624        return rawLimits
3625
3626    def OverviewLimits(self, show: bool = False) -> dict:
3627        """
3628        Method for parsing and show table with available funds for withdrawal for current `accountId`.
3629
3630        See also: `RequestLimits()`.
3631
3632        :param show: if `False` then only dictionary returns, if `True` then also print withdrawal limits to log.
3633        :return: dict with raw parsed data from server and some calculated statistics about it.
3634        """
3635        if self.accountId is None or not self.accountId:
3636            uLogger.error("Variable `accountId` must be defined for using this method!")
3637            raise Exception("Account ID required")
3638
3639        rawLimits = self.RequestLimits()  # raw response with current available funds for withdrawal
3640
3641        view = {
3642            "rawLimits": rawLimits,
3643            "limits": {  # parsed data for every currency:
3644                "money": {  # this is an array of portfolio currency positions
3645                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["money"]
3646                },
3647                "blocked": {  # this is an array of blocked currency
3648                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blocked"]
3649                },
3650                "blockedGuarantee": {  # this is locked money under collateral for futures
3651                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blockedGuarantee"]
3652                },
3653            },
3654        }
3655
3656        # --- Prepare text table with limits in human-readable format:
3657        if show:
3658            info = [
3659                "# Withdrawal limits\n\n",
3660                "* **Actual date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
3661                "* **Account ID:** [{}]\n".format(self.accountId),
3662            ]
3663
3664            if view["limits"]["money"]:
3665                info.extend([
3666                    "\n| Currencies | Total         | Available for withdrawal | Blocked for trade | Futures guarantee |\n",
3667                    "|------------|---------------|--------------------------|-------------------|-------------------|\n",
3668                ])
3669
3670            else:
3671                info.append("\nNo withdrawal limits\n")
3672
3673            for curr in view["limits"]["money"].keys():
3674                blocked = view["limits"]["blocked"][curr] if curr in view["limits"]["blocked"].keys() else 0
3675                blockedGuarantee = view["limits"]["blockedGuarantee"][curr] if curr in view["limits"]["blockedGuarantee"].keys() else 0
3676                availableMoney = view["limits"]["money"][curr] - (blocked + blockedGuarantee)
3677
3678                infoStr = "| {:<10} | {:<13} | {:<24} | {:<17} | {:<17} |\n".format(
3679                    "[{}]".format(curr),
3680                    "{:.2f}".format(view["limits"]["money"][curr]),
3681                    "{:.2f}".format(availableMoney),
3682                    "{:.2f}".format(view["limits"]["blocked"][curr]) if curr in view["limits"]["blocked"].keys() else "—",
3683                    "{:.2f}".format(view["limits"]["blockedGuarantee"][curr]) if curr in view["limits"]["blockedGuarantee"].keys() else "—",
3684                )
3685
3686                if curr == "rub":
3687                    info.insert(5, infoStr)  # hack: insert "rub" at the first position in table and after headers
3688
3689                else:
3690                    info.append(infoStr)
3691
3692            infoText = "".join(info)
3693
3694            uLogger.info(infoText)
3695
3696            if self.withdrawalLimitsFile:
3697                with open(self.withdrawalLimitsFile, "w", encoding="UTF-8") as fH:
3698                    fH.write(infoText)
3699
3700                uLogger.info("Client's withdrawal limits was saved to file: [{}]".format(os.path.abspath(self.withdrawalLimitsFile)))
3701
3702        return view
3703
3704    def RequestAccounts(self) -> dict:
3705        """
3706        Method for requesting all brokerage accounts (`accountId`s) of current user detected by `token`.
3707
3708        See also:
3709        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
3710        - What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
3711        - `OverviewUserInfo()` method
3712
3713        :return: dict with raw data from server that contains accounts info. Example of dict:
3714                 `{"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account",
3715                   "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z",
3716                   "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}`.
3717                 If `closedDate="1970-01-01T00:00:00Z"` it means that account is active now.
3718        """
3719        uLogger.debug("Requesting all brokerage accounts of current user detected by its token. Wait, please...")
3720
3721        self.body = str({})
3722        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetAccounts"
3723        rawAccounts = self.SendAPIRequest(portfolioURL, reqType="POST")
3724
3725        if self.moreDebug:
3726            uLogger.debug("Records about available accounts successfully received")
3727
3728        return rawAccounts
3729
3730    def RequestUserInfo(self) -> dict:
3731        """
3732        Method for requesting common user's information.
3733
3734        See also:
3735        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
3736        - What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
3737        - What does `qualified_for_work_with` field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
3738        - `OverviewUserInfo()` method
3739
3740        :return: dict with raw data from server that contains user's information. Example of dict:
3741                 `{"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage",
3742                   "russian_shares", "structured_income_bonds"], "tariff": "premium"}`.
3743        """
3744        uLogger.debug("Requesting common user's information. Wait, please...")
3745
3746        self.body = str({})
3747        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetInfo"
3748        rawUserInfo = self.SendAPIRequest(portfolioURL, reqType="POST")
3749
3750        if self.moreDebug:
3751            uLogger.debug("Records about current user successfully received")
3752
3753        return rawUserInfo
3754
3755    def RequestMarginStatus(self, accountId: str = None) -> dict:
3756        """
3757        Method for requesting margin calculation for defined account ID.
3758
3759        See also:
3760        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
3761        - What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
3762        - `OverviewUserInfo()` method
3763
3764        :param accountId: string with numeric account ID. If `None`, then used class field `accountId`.
3765        :return: dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict.
3766                 Example of responses:
3767                 status code 400: `{"code": 3, "message": "account margin status is disabled", "description": "30051" }`, returns: `{}`.
3768                 status code 200: `{"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000},
3769                                    "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000},
3770                                    "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000},
3771                                    "fundsSufficiencyLevel": {"units": "1", "nano": 280000000},
3772                                    "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}`.
3773        """
3774        if accountId is None or not accountId:
3775            if self.accountId is None or not self.accountId:
3776                uLogger.error("Variable `accountId` must be defined for using this method!")
3777                raise Exception("Account ID required")
3778
3779            else:
3780                accountId = self.accountId  # use `self.accountId` (main ID) by default
3781
3782        uLogger.debug("Requesting margin calculation for accountId [{}]. Wait, please...".format(accountId))
3783
3784        self.body = str({"accountId": accountId})
3785        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetMarginAttributes"
3786        rawMargin = self.SendAPIRequest(portfolioURL, reqType="POST")
3787
3788        if rawMargin == {"code": 3, "message": "account margin status is disabled", "description": "30051"}:
3789            uLogger.debug("Server response: margin status is disabled for current accountId [{}]".format(accountId))
3790            rawMargin = {}
3791
3792        else:
3793            if self.moreDebug:
3794                uLogger.debug("Records with margin calculation for accountId [{}] successfully received".format(accountId))
3795
3796        return rawMargin
3797
3798    def RequestTariffLimits(self) -> dict:
3799        """
3800        Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by `token`.
3801
3802        See also:
3803        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
3804        - What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
3805        - Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
3806        - Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
3807        - `OverviewUserInfo()` method
3808
3809        :return: dict with raw data from server that contains limits of current tariff. Example of dict:
3810                 `{"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...],
3811                   "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}`.
3812        """
3813        uLogger.debug("Requesting limits of current tariff. Wait, please...")
3814
3815        self.body = str({})
3816        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetUserTariff"
3817        rawTariffLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3818
3819        if self.moreDebug:
3820            uLogger.debug("Records with limits of current tariff successfully received")
3821
3822        return rawTariffLimits
3823
3824    def RequestBondCoupons(self, iJSON: dict) -> dict:
3825        """
3826        Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown
3827        then requesting dates `"from": "1970-01-01T00:00:00.000Z"` and `"to": "2099-12-31T23:59:59.000Z"`.
3828        All dates are in UTC timezone.
3829
3830        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons
3831        Documentation:
3832        - request: https://tinkoff.github.io/investAPI/instruments/#getbondcouponsrequest
3833        - response: https://tinkoff.github.io/investAPI/instruments/#coupon
3834
3835        See also: `ExtendBondsData()`.
3836
3837        :param iJSON: raw json data of a bond from broker server, example `iJSON = self.iList["Bonds"][self.ticker]`
3838                      If raw iJSON is not data of bond then server returns an error [400] with message:
3839                      `{"code": 3, "message": "instrument type is not bond", "description": "30048"}`.
3840        :return: dictionary with bond payment calendar. Response example
3841                 `{"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12",
3842                   "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000},
3843                   "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z",
3844                   "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}`
3845        """
3846        if iJSON["figi"] is None or not iJSON["figi"]:
3847            uLogger.error("FIGI must be defined for using this method!")
3848            raise Exception("FIGI required")
3849
3850        startDate = iJSON["placementDate"] if "placementDate" in iJSON.keys() else "1970-01-01T00:00:00.000Z"
3851        endDate = iJSON["maturityDate"] if "maturityDate" in iJSON.keys() else "2099-12-31T23:59:59.000Z"
3852
3853        uLogger.debug("Requesting bond payment calendar, {}FIGI: [{}], from: [{}], to: [{}]. Wait, please...".format(
3854            "ticker: [{}], ".format(iJSON["ticker"]) if "ticker" in iJSON.keys() else "",
3855            self.figi,
3856            startDate,
3857            endDate,
3858        ))
3859
3860        self.body = str({"figi": iJSON["figi"], "from": startDate, "to": endDate})
3861        calendarURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/GetBondCoupons"
3862        calendar = self.SendAPIRequest(calendarURL, reqType="POST")
3863
3864        if calendar == {"code": 3, "message": "instrument type is not bond", "description": "30048"}:
3865            uLogger.warning("Instrument type is not bond!")
3866
3867        else:
3868            if self.moreDebug:
3869                uLogger.debug("Records about bond payment calendar successfully received")
3870
3871        return calendar
3872
3873    def ExtendBondsData(self, instruments: list[str], xlsx: bool = False) -> pd.DataFrame:
3874        """
3875        Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider
3876        Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar,
3877        coupon yields, current yields and some statistics etc.
3878
3879        WARNING! This is too long operation if a lot of bonds requested from broker server.
3880
3881        See also: `ShowInstrumentInfo()`, `CreateBondsCalendar()`, `ShowBondsCalendar()`, `RequestBondCoupons()`.
3882
3883        :param instruments: list of strings with tickers or FIGIs.
3884        :param xlsx: if True then also exports Pandas DataFrame to xlsx-file `bondsXLSXFile`, default `ext-bonds.xlsx`,
3885                     for further used by data scientists or stock analytics.
3886        :return: wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker.
3887                 In XLSX-file and Pandas DataFrame fields mean:
3888                 - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond
3889                 - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon
3890        """
3891        if instruments is None or not instruments:
3892            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3893            raise Exception("Ticker or FIGI required")
3894
3895        if isinstance(instruments, str):
3896            instruments = [instruments]
3897
3898        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3899
3900        uLogger.debug("Requesting raw bonds calendar from server, transforming and extending it. Wait, please...")
3901
3902        iCount = len(uniqueInstruments)
3903        tooLong = iCount >= 20
3904        if tooLong:
3905            uLogger.warning("You requested a lot of bonds! Operation will takes more time. Wait, please...")
3906
3907        bonds = None
3908        for i, self.figi in enumerate(uniqueInstruments):
3909            instrument = self.SearchByFIGI(requestPrice=False)  # raw data about instrument from server
3910
3911            if "type" in instrument.keys() and instrument["type"] == "Bonds":
3912                # raw bond data from server where fields mean: https://tinkoff.github.io/investAPI/instruments/#bond
3913                rawBond = self.SearchByFIGI(requestPrice=True)
3914
3915                # Widen raw data with UTC current time (iData["actualDateTime"]):
3916                actualDate = datetime.now(tzutc())
3917                iData = {"actualDateTime": actualDate.strftime(TKS_DATE_TIME_FORMAT)} | rawBond
3918
3919                # Widen raw data with bond payment calendar (iData["rawCalendar"]):
3920                iData = iData | {"rawCalendar": self.RequestBondCoupons(iJSON=iData)}
3921
3922                # Replace some values with human-readable:
3923                iData["nominalCurrency"] = iData["nominal"]["currency"]
3924                iData["nominal"] = NanoToFloat(iData["nominal"]["units"], iData["nominal"]["nano"])
3925                iData["placementPrice"] = NanoToFloat(iData["placementPrice"]["units"], iData["placementPrice"]["nano"])
3926                iData["aciCurrency"] = iData["aciValue"]["currency"]
3927                iData["aciValue"] = NanoToFloat(iData["aciValue"]["units"], iData["aciValue"]["nano"])
3928                iData["issueSize"] = int(iData["issueSize"])
3929                iData["issueSizePlan"] = int(iData["issueSizePlan"])
3930                iData["tradingStatus"] = TKS_TRADING_STATUSES[iData["tradingStatus"]]
3931                iData["step"] = iData["step"] if "step" in iData.keys() else 0
3932                iData["realExchange"] = TKS_REAL_EXCHANGES[iData["realExchange"]]
3933                iData["klong"] = NanoToFloat(iData["klong"]["units"], iData["klong"]["nano"]) if "klong" in iData.keys() else 0
3934                iData["kshort"] = NanoToFloat(iData["kshort"]["units"], iData["kshort"]["nano"]) if "kshort" in iData.keys() else 0
3935                iData["dlong"] = NanoToFloat(iData["dlong"]["units"], iData["dlong"]["nano"]) if "dlong" in iData.keys() else 0
3936                iData["dshort"] = NanoToFloat(iData["dshort"]["units"], iData["dshort"]["nano"]) if "dshort" in iData.keys() else 0
3937                iData["dlongMin"] = NanoToFloat(iData["dlongMin"]["units"], iData["dlongMin"]["nano"]) if "dlongMin" in iData.keys() else 0
3938                iData["dshortMin"] = NanoToFloat(iData["dshortMin"]["units"], iData["dshortMin"]["nano"]) if "dshortMin" in iData.keys() else 0
3939
3940                # Widen raw data with price fields from `currentPrice` values (all prices are actual at `actualDateTime` date):
3941                iData["limitUpPercent"] = iData["currentPrice"]["limitUp"]  # max price on current day in percents of nominal
3942                iData["limitDownPercent"] = iData["currentPrice"]["limitDown"]  # min price on current day in percents of nominal
3943                iData["lastPricePercent"] = iData["currentPrice"]["lastPrice"]  # last price on market in percents of nominal
3944                iData["closePricePercent"] = iData["currentPrice"]["closePrice"]  # previous day close in percents of nominal
3945                iData["changes"] = iData["currentPrice"]["changes"]  # this is percent of changes between `currentPrice` and `lastPrice`
3946                iData["limitUp"] = iData["limitUpPercent"] * iData["nominal"] / 100  # max price on current day is `limitUpPercent` * `nominal`
3947                iData["limitDown"] = iData["limitDownPercent"] * iData["nominal"] / 100  # min price on current day is `limitDownPercent` * `nominal`
3948                iData["lastPrice"] = iData["lastPricePercent"] * iData["nominal"] / 100  # last price on market is `lastPricePercent` * `nominal`
3949                iData["closePrice"] = iData["closePricePercent"] * iData["nominal"] / 100  # previous day close is `closePricePercent` * `nominal`
3950                iData["changesDelta"] = iData["lastPrice"] - iData["closePrice"]  # this is delta between last deal price and last close
3951
3952                # Widen raw data with calendar data from `rawCalendar` values:
3953                calendarData = []
3954                if "events" in iData["rawCalendar"].keys():
3955                    for item in iData["rawCalendar"]["events"]:
3956                        calendarData.append({
3957                            "couponDate": item["couponDate"],
3958                            "couponNumber": int(item["couponNumber"]),
3959                            "fixDate": item["fixDate"] if "fixDate" in item.keys() else "",
3960                            "payCurrency": item["payOneBond"]["currency"],
3961                            "payOneBond": NanoToFloat(item["payOneBond"]["units"], item["payOneBond"]["nano"]),
3962                            "couponType": TKS_COUPON_TYPES[item["couponType"]],
3963                            "couponStartDate": item["couponStartDate"],
3964                            "couponEndDate": item["couponEndDate"],
3965                            "couponPeriod": item["couponPeriod"],
3966                        })
3967
3968                    # if maturity date is unknown then uses the latest date in bond payment calendar for it:
3969                    if "maturityDate" not in iData.keys():
3970                        iData["maturityDate"] = datetime.strptime(calendarData[0]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT) if calendarData else ""
3971
3972                # Widen raw data with Coupon Rate.
3973                # This is sum of all coupon payments divided on nominal price and expire days sum and then multiple on 365 days and 100%:
3974                iData["sumCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData])
3975                iData["periodDays"] = sum([coupon["couponPeriod"] for coupon in calendarData])
3976                iData["couponsYield"] = 100 * 365 * (iData["sumCoupons"] / iData["nominal"]) / iData["periodDays"] if iData["nominal"] != 0 and iData["periodDays"] != 0 else 0.
3977
3978                # Widen raw data with Yield to Maturity (YTM) on current date.
3979                # This is sum of all stayed coupons to maturity minus ACI and divided on current bond price and then multiple on stayed days and 100%:
3980                maturityDate = datetime.strptime(iData["maturityDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) if iData["maturityDate"] else None
3981                iData["daysToMaturity"] = (maturityDate - actualDate).days if iData["maturityDate"] else None
3982                iData["sumLastCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData if datetime.strptime(coupon["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) > actualDate])
3983                iData["lastPayments"] = iData["sumLastCoupons"] - iData["aciValue"]  # sum of all last coupons minus current ACI value
3984                iData["currentYield"] = 100 * 365 * (iData["lastPayments"] / iData["lastPrice"]) / iData["daysToMaturity"] if iData["lastPrice"] != 0 and iData["daysToMaturity"] != 0 else 0.
3985
3986                iData["calendar"] = calendarData  # adds calendar at the end
3987
3988                # Remove not used data:
3989                iData.pop("uid")
3990                iData.pop("positionUid")
3991                iData.pop("currentPrice")
3992                iData.pop("rawCalendar")
3993
3994                colNames = list(iData.keys())
3995                if bonds is None:
3996                    bonds = pd.DataFrame(data=pd.DataFrame.from_records(data=[iData], columns=colNames))
3997
3998                else:
3999                    bonds = pd.concat([bonds, pd.DataFrame.from_records(data=[iData], columns=colNames)], axis=0, ignore_index=True)
4000
4001            else:
4002                uLogger.warning("Instrument is not a bond!")
4003
4004            processed = round(100 * (i + 1) / iCount, 1)
4005            if tooLong and processed % 5 == 0:
4006                uLogger.info("{}% processed [{} / {}]...".format(round(processed), i + 1, iCount))
4007
4008            else:
4009                uLogger.debug("{}% bonds processed [{} / {}]...".format(processed, i + 1, iCount))
4010
4011        bonds.index = bonds["ticker"].tolist()  # replace indexes with ticker names
4012
4013        # Saving bonds from Pandas DataFrame to XLSX sheet:
4014        if xlsx and self.bondsXLSXFile:
4015            with pd.ExcelWriter(
4016                    path=self.bondsXLSXFile,
4017                    date_format=TKS_DATE_FORMAT,
4018                    datetime_format=TKS_DATE_TIME_FORMAT,
4019                    mode="w",
4020            ) as writer:
4021                bonds.to_excel(
4022                    writer,
4023                    sheet_name="Extended bonds data",
4024                    index=True,
4025                    encoding="UTF-8",
4026                    freeze_panes=(1, 1),
4027                )  # saving as XLSX-file with freeze first row and column as headers
4028
4029            uLogger.info("XLSX-file with extended bonds data for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(self.bondsXLSXFile)))
4030
4031        return bonds
4032
4033    def CreateBondsCalendar(self, extBonds: pd.DataFrame, xlsx: bool = False) -> pd.DataFrame:
4034        """
4035        Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, `calendar.xlsx` by default.
4036
4037        WARNING! This is too long operation if a lot of bonds requested from broker server.
4038
4039        See also: `ShowBondsCalendar()`, `ExtendBondsData()`.
4040
4041        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4042                        extended information about bonds: main info, current prices, bond payment calendar,
4043                        coupon yields, current yields and some statistics etc.
4044                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4045        :param xlsx: if True then also exports Pandas DataFrame to file `calendarFile` + `".xlsx"`, `calendar.xlsx` by default,
4046                     for further used by data scientists or stock analytics.
4047        :return: Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon
4048        """
4049        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4050            extBonds = self.ExtendBondsData(instruments=[self.figi, self.ticker], xlsx=False)
4051
4052        uLogger.debug("Generating bond payments calendar data. Wait, please...")
4053
4054        colNames = ["Paid", "Payment date", "FIGI", "Ticker", "Name", "No.", "Value", "Currency", "Coupon type", "Period", "End registry date", "Coupon start date", "Coupon end date"]
4055        colID = ["paid", "couponDate", "figi", "ticker", "name", "couponNumber", "payOneBond", "payCurrency", "couponType", "couponPeriod", "fixDate", "couponStartDate", "couponEndDate"]
4056        calendar = None
4057        for bond in extBonds.iterrows():
4058            for item in bond[1]["calendar"]:
4059                cData = {
4060                    "paid": datetime.now(tzutc()) > datetime.strptime(item["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()),
4061                    "couponDate": item["couponDate"],
4062                    "figi": bond[1]["figi"],
4063                    "ticker": bond[1]["ticker"],
4064                    "name": bond[1]["name"],
4065                    "couponNumber": item["couponNumber"],
4066                    "payOneBond": item["payOneBond"],
4067                    "payCurrency": item["payCurrency"],
4068                    "couponType": item["couponType"],
4069                    "couponPeriod": item["couponPeriod"],
4070                    "fixDate": item["fixDate"],
4071                    "couponStartDate": item["couponStartDate"],
4072                    "couponEndDate": item["couponEndDate"],
4073                }
4074
4075                if calendar is None:
4076                    calendar = pd.DataFrame(data=pd.DataFrame.from_records(data=[cData], columns=colID))
4077
4078                else:
4079                    calendar = pd.concat([calendar, pd.DataFrame.from_records(data=[cData], columns=colID)], axis=0, ignore_index=True)
4080
4081        if calendar is not None:
4082            calendar = calendar.sort_values(by=["couponDate"], axis=0, ascending=True)  # sort all payments for all bonds by payment date
4083
4084            # Saving calendar from Pandas DataFrame to XLSX sheet:
4085            if xlsx:
4086                xlsxCalendarFile = self.calendarFile.replace(".md", ".xlsx") if self.calendarFile.endswith(".md") else self.calendarFile + ".xlsx"
4087
4088                with pd.ExcelWriter(
4089                        path=xlsxCalendarFile,
4090                        date_format=TKS_DATE_FORMAT,
4091                        datetime_format=TKS_DATE_TIME_FORMAT,
4092                        mode="w",
4093                ) as writer:
4094                    humanReadable = calendar.copy(deep=True)
4095                    humanReadable["couponDate"] = humanReadable["couponDate"].apply(lambda x: x.split("T")[0])
4096                    humanReadable["fixDate"] = humanReadable["fixDate"].apply(lambda x: x.split("T")[0])
4097                    humanReadable["couponStartDate"] = humanReadable["couponStartDate"].apply(lambda x: x.split("T")[0])
4098                    humanReadable["couponEndDate"] = humanReadable["couponEndDate"].apply(lambda x: x.split("T")[0])
4099                    humanReadable.columns = colNames  # human-readable column names
4100
4101                    humanReadable.to_excel(
4102                        writer,
4103                        sheet_name="Bond payments calendar",
4104                        index=False,
4105                        encoding="UTF-8",
4106                        freeze_panes=(1, 2),
4107                    )  # saving as XLSX-file with freeze first row and column as headers
4108
4109                    del humanReadable  # release df in memory
4110
4111                uLogger.info("XLSX-file with bond payments calendar for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxCalendarFile)))
4112
4113        return calendar
4114
4115    def ShowBondsCalendar(self, extBonds: pd.DataFrame, show: bool = True) -> str:
4116        """
4117        Show bond payments calendar as a table. One row in input `bonds` dataframe contains one bond.
4118        Also, creates Markdown file with calendar data, `calendar.md` by default.
4119
4120        See also: `ShowInstrumentInfo()`, `RequestBondCoupons()`, `CreateBondsCalendar()` and `ExtendBondsData()`.
4121
4122        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4123                        extended information about bonds: main info, current prices, bond payment calendar,
4124                        coupon yields, current yields and some statistics etc.
4125                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4126        :param show: if `True` then also printing bonds payment calendar to the console,
4127                     otherwise save to file `calendarFile` only. `False` by default.
4128        :return: multilines text in Markdown format with bonds payment calendar as a table.
4129        """
4130        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4131            extBonds = self.ExtendBondsData(instruments=[self.figi, self.ticker], xlsx=False)
4132
4133        infoText = "# Bond payments calendar\n\n"
4134
4135        calendar = self.CreateBondsCalendar(extBonds, xlsx=True)  # generate Pandas DataFrame with full calendar data
4136
4137        if not (calendar is None or calendar.empty):
4138            splitLine = "|       |                 |              |              |     |               |           |        |                   |\n"
4139
4140            info = [
4141                "| Paid  | Payment date    | FIGI         | Ticker       | No. | Value         | Type      | Period | End registry date |\n",
4142                "|-------|-----------------|--------------|--------------|-----|---------------|-----------|--------|-------------------|\n",
4143            ]
4144
4145            newMonth = False
4146            notOneBond = calendar["figi"].nunique() > 1
4147            for i, bond in enumerate(calendar.iterrows()):
4148                if newMonth and notOneBond:
4149                    info.append(splitLine)
4150
4151                info.append(
4152                    "| {:<5} | {:<15} | {:<12} | {:<12} | {:<3} | {:<13} | {:<9} | {:<6} | {:<17} |\n".format(
4153                        "  √" if bond[1]["paid"] else "  —",
4154                        bond[1]["couponDate"].split("T")[0],
4155                        bond[1]["figi"],
4156                        bond[1]["ticker"],
4157                        bond[1]["couponNumber"],
4158                        "{} {}".format(
4159                            "{}".format(round(bond[1]["payOneBond"], 6)).rstrip("0").rstrip("."),
4160                            bond[1]["payCurrency"],
4161                        ),
4162                        bond[1]["couponType"],
4163                        bond[1]["couponPeriod"],
4164                        bond[1]["fixDate"].split("T")[0],
4165                    )
4166                )
4167
4168                if i < len(calendar.values) - 1:
4169                    curDate = datetime.strptime(bond[1]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4170                    nextDate = datetime.strptime(calendar["couponDate"].values[i + 1], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4171                    newMonth = False if curDate.month == nextDate.month else True
4172
4173                else:
4174                    newMonth = False
4175
4176            infoText += "".join(info)
4177
4178            if show:
4179                uLogger.info("{}".format(infoText))
4180
4181            if self.calendarFile is not None:
4182                with open(self.calendarFile, "w", encoding="UTF-8") as fH:
4183                    fH.write(infoText)
4184
4185                uLogger.info("Bond payment calendar was saved to file: [{}]".format(os.path.abspath(self.calendarFile)))
4186
4187        else:
4188            infoText += "No data\n"
4189
4190        return infoText
4191
4192    def OverviewAccounts(self, show: bool = False) -> dict:
4193        """
4194        Method for parsing and show simple table with all available user accounts.
4195
4196        See also: `RequestAccounts()` and `OverviewUserInfo()` methods.
4197
4198        :param show: if `False` then only dictionary with accounts data returns, if `True` then also print it to log.
4199        :return: dict with parsed accounts data received from `RequestAccounts()` method. Example of dict:
4200                 `view = {"rawAccounts": {rawAccounts from RequestAccounts() method...},
4201                          "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1",
4202                                                        "status": "Opened and active account", "opened": "2018-05-23 00:00:00",
4203                                                        "closed": "—", "access": "Full access" }, ...}}`
4204        """
4205        rawAccounts = self.RequestAccounts()  # Raw responses with accounts
4206
4207        # This is an array of dict with user accounts, its `accountId`s and some parsed data:
4208        accounts = {
4209            item["id"]: {
4210                "type": TKS_ACCOUNT_TYPES[item["type"]],
4211                "name": item["name"],
4212                "status": TKS_ACCOUNT_STATUSES[item["status"]],
4213                "opened": datetime.strptime(item["openedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4214                "closed": datetime.strptime(item["closedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if item["closedDate"] != "1970-01-01T00:00:00Z" else "—",
4215                "access": TKS_ACCESS_LEVELS[item["accessLevel"]],
4216            } for item in rawAccounts["accounts"]
4217        }
4218
4219        # Raw and parsed data with some fields replaced in "stat" section:
4220        view = {
4221            "rawAccounts": rawAccounts,
4222            "stat": accounts,
4223        }
4224
4225        # --- Prepare simple text table with only accounts data in human-readable format:
4226        if show:
4227            info = [
4228                "# User accounts\n\n",
4229                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4230                "| Account ID   | Type                      | Status                    | Name                           |\n",
4231                "|--------------|---------------------------|---------------------------|--------------------------------|\n",
4232            ]
4233
4234            for account in view["stat"].keys():
4235                info.extend([
4236                    "| {:<12} | {:<25} | {:<25} | {:<30} |\n".format(
4237                        account,
4238                        view["stat"][account]["type"],
4239                        view["stat"][account]["status"],
4240                        view["stat"][account]["name"],
4241                    )
4242                ])
4243
4244            infoText = "".join(info)
4245
4246            uLogger.info(infoText)
4247
4248            if self.userAccountsFile:
4249                with open(self.userAccountsFile, "w", encoding="UTF-8") as fH:
4250                    fH.write(infoText)
4251
4252                uLogger.info("User accounts were saved to file: [{}]".format(os.path.abspath(self.userAccountsFile)))
4253
4254        return view
4255
4256    def OverviewUserInfo(self, show: bool = False) -> dict:
4257        """
4258        Method for parsing and show all available user's data (`accountId`s, common user information, margin status and tariff connections limit).
4259
4260        See also: `OverviewAccounts()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()` methods.
4261
4262        :param show: if `False` then only dictionary returns, if `True` then also print user's data to log.
4263        :return: dict with raw parsed data from server and some calculated statistics about it.
4264        """
4265        rawUserInfo = self.RequestUserInfo()  # Raw response with common user info
4266        overviewAccount = self.OverviewAccounts(show=False)  # Raw and parsed accounts data
4267        rawAccounts = overviewAccount["rawAccounts"]  # Raw response with user accounts data
4268        accounts = overviewAccount["stat"]  # Dict with only statistics about user accounts
4269        rawMargins = {account: self.RequestMarginStatus(accountId=account) for account in accounts.keys()}  # Raw response with margin calculation for every account ID
4270        rawTariffLimits = self.RequestTariffLimits()  # Raw response with limits of current tariff
4271
4272        # This is dict with parsed common user data:
4273        userInfo = {
4274            "premium": "Yes" if rawUserInfo["premStatus"] else "No",
4275            "qualified": "Yes" if rawUserInfo["qualStatus"] else "No",
4276            "allowed": [TKS_QUALIFIED_TYPES[item] for item in rawUserInfo["qualifiedForWorkWith"]],
4277            "tariff": rawUserInfo["tariff"],
4278        }
4279
4280        # This is an array of dict with parsed margin statuses for every account IDs:
4281        margins = {}
4282        for accountId in accounts.keys():
4283            if rawMargins[accountId]:
4284                margins[accountId] = {
4285                    "currency": rawMargins[accountId]["liquidPortfolio"]["currency"],
4286                    "liquid": NanoToFloat(rawMargins[accountId]["liquidPortfolio"]["units"], rawMargins[accountId]["liquidPortfolio"]["nano"]),
4287                    "start": NanoToFloat(rawMargins[accountId]["startingMargin"]["units"], rawMargins[accountId]["startingMargin"]["nano"]),
4288                    "min": NanoToFloat(rawMargins[accountId]["minimalMargin"]["units"], rawMargins[accountId]["minimalMargin"]["nano"]),
4289                    "level": NanoToFloat(rawMargins[accountId]["fundsSufficiencyLevel"]["units"], rawMargins[accountId]["fundsSufficiencyLevel"]["nano"]),
4290                    "missing": NanoToFloat(rawMargins[accountId]["amountOfMissingFunds"]["units"], rawMargins[accountId]["amountOfMissingFunds"]["nano"]),
4291                }
4292
4293            else:
4294                margins[accountId] = {}  # Server response: margin status is disabled for current accountId
4295
4296        unary = {}  # unary-connection limits
4297        for item in rawTariffLimits["unaryLimits"]:
4298            if item["limitPerMinute"] in unary.keys():
4299                unary[item["limitPerMinute"]].extend(item["methods"])
4300
4301            else:
4302                unary[item["limitPerMinute"]] = item["methods"]
4303
4304        stream = {}  # stream-connection limits
4305        for item in rawTariffLimits["streamLimits"]:
4306            if item["limit"] in stream.keys():
4307                stream[item["limit"]].extend(item["streams"])
4308
4309            else:
4310                stream[item["limit"]] = item["streams"]
4311
4312        # This is dict with parsed limits of current tariff (connections, API methods etc.):
4313        limits = {
4314            "unary": unary,
4315            "stream": stream,
4316        }
4317
4318        # Raw and parsed data as an output result:
4319        view = {
4320            "rawUserInfo": rawUserInfo,
4321            "rawAccounts": rawAccounts,
4322            "rawMargins": rawMargins,
4323            "rawTariffLimits": rawTariffLimits,
4324            "stat": {
4325                "userInfo": userInfo,
4326                "accounts": accounts,
4327                "margins": margins,
4328                "limits": limits,
4329            },
4330        }
4331
4332        # --- Prepare text table with user information in human-readable format:
4333        if show:
4334            info = [
4335                "# Full user information\n\n",
4336                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4337                "## Common information\n\n",
4338                "* **Qualified user:** {}\n".format(view["stat"]["userInfo"]["qualified"]),
4339                "* **Tariff name:** {}\n".format(view["stat"]["userInfo"]["tariff"]),
4340                "* **Premium user:** {}\n".format(view["stat"]["userInfo"]["premium"]),
4341                "* **Allowed to work with instruments:**\n{}\n".format("".join(["  - {}\n".format(item) for item in view["stat"]["userInfo"]["allowed"]])),
4342                "\n## User accounts\n\n",
4343            ]
4344
4345            for account in view["stat"]["accounts"].keys():
4346                info.extend([
4347                    "### ID: [{}]\n\n".format(account),
4348                    "| Parameters           | Values                                                       |\n",
4349                    "|----------------------|--------------------------------------------------------------|\n",
4350                    "| Account type:        | {:<60} |\n".format(view["stat"]["accounts"][account]["type"]),
4351                    "| Account name:        | {:<60} |\n".format(view["stat"]["accounts"][account]["name"]),
4352                    "| Account status:      | {:<60} |\n".format(view["stat"]["accounts"][account]["status"]),
4353                    "| Access level:        | {:<60} |\n".format(view["stat"]["accounts"][account]["access"]),
4354                    "| Date opened:         | {:<60} |\n".format(view["stat"]["accounts"][account]["opened"]),
4355                    "| Date closed:         | {:<60} |\n".format(view["stat"]["accounts"][account]["closed"]),
4356                ])
4357
4358                if margins[account]:
4359                    info.extend([
4360                        "| Margin status:       | Enabled                                                      |\n",
4361                        "| - Liquid portfolio:  | {:<60} |\n".format("{} {}".format(margins[account]["liquid"], margins[account]["currency"])),
4362                        "| - Margin starting:   | {:<60} |\n".format("{} {}".format(margins[account]["start"], margins[account]["currency"])),
4363                        "| - Margin minimum:    | {:<60} |\n".format("{} {}".format(margins[account]["min"], margins[account]["currency"])),
4364                        "| - Sufficiency level: | {:<60} |\n".format("{:.2f} ({:.2f}%)".format(margins[account]["level"], margins[account]["level"] * 100)),
4365                        "| - Missing funds:     | {:<60} |\n\n".format("{} {}".format(margins[account]["missing"], margins[account]["currency"])),
4366                    ])
4367
4368                else:
4369                    info.append("| Margin status:       | Disabled                                                     |\n\n")
4370
4371            info.extend([
4372                "\n## Current user tariff limits\n",
4373                "\nSee also:\n",
4374                "* Tinkoff limit policy: https://tinkoff.github.io/investAPI/limits/\n",
4375                "* Tinkoff Invest API: https://tinkoff.github.io/investAPI/\n",
4376                "  - More about REST API requests: https://tinkoff.github.io/investAPI/swagger-ui/\n",
4377                "  - More about gRPC requests for stream connections: https://tinkoff.github.io/investAPI/grpc/\n",
4378                "\n### Unary limits\n",
4379            ])
4380
4381            if unary:
4382                for key, values in sorted(unary.items()):
4383                    info.append("\n* Max requests per minute: {}\n".format(key))
4384
4385                    for value in values:
4386                        info.append("  - {}\n".format(value))
4387
4388            else:
4389                info.append("\nNot available\n")
4390
4391            info.append("\n### Stream limits\n")
4392
4393            if stream:
4394                for key, values in sorted(stream.items()):
4395                    info.append("\n* Max stream connections: {}\n".format(key))
4396
4397                    for value in values:
4398                        info.append("  - {}\n".format(value))
4399
4400            else:
4401                info.append("\nNot available\n")
4402
4403            infoText = "".join(info)
4404
4405            uLogger.info(infoText)
4406
4407            if self.userInfoFile:
4408                with open(self.userInfoFile, "w", encoding="UTF-8") as fH:
4409                    fH.write(infoText)
4410
4411                uLogger.info("User data was saved to file: [{}]".format(os.path.abspath(self.userInfoFile)))
4412
4413        return view
4414
4415
4416class Args:
4417    """
4418    If `Main()` function is imported as module, then this class used to convert arguments from **kwargs as object.
4419    """
4420    def __init__(self, **kwargs):
4421        self.__dict__.update(kwargs)
4422
4423    def __getattr__(self, item):
4424        return None
4425
4426
4427def ParseArgs():
4428    """This function get and parse command line keys."""
4429    parser = ArgumentParser()  # command-line string parser
4430
4431    parser.description = "TKSBrokerAPI is a trading platform for automation on Python to simplify the implementation of trading scenarios and work with Tinkoff Invest API server via the REST protocol. See examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md"
4432    parser.usage = "\n/as module/ python TKSBrokerAPI.py [some options] [one command]\n/as CLI tool/ tksbrokerapi [some options] [one command]"
4433
4434    # --- options:
4435
4436    parser.add_argument("--no-cache", action="store_true", default=False, help="Option: not use local cache `dump.json`, but update raw instruments data when starting the platform. `False` by default.")
4437    parser.add_argument("--token", type=str, help="Option: Tinkoff service's api key. If not set then used environment variable `TKS_API_TOKEN`. See how to use: https://tinkoff.github.io/investAPI/token/")
4438    parser.add_argument("--account-id", type=str, default=None, help="Option: string with an user numeric account ID in Tinkoff Broker. It can be found in any broker's reports (see the contract number). Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.")
4439
4440    parser.add_argument("--ticker", "-t", type=str, help="Option: instrument's ticker, e.g. `IBM`, `YNDX`, `GOOGL` etc. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR`.")
4441    parser.add_argument("--figi", "-f", type=str, help="Option: instrument's FIGI, e.g. `BBG006L8G4H1` (for `YNDX`).")
4442
4443    parser.add_argument("--depth", type=int, default=1, help="Option: Depth of Market (DOM) can be >=1, 1 by default.")
4444    parser.add_argument("--no-cancelled", "--no-canceled", action="store_true", default=False, help="Option: remove information about cancelled operations from the deals report by the `--deals` key. `False` by default.")
4445
4446    parser.add_argument("--output", type=str, default=None, help="Option: replace default paths to output files for some commands. If `None` then used default files.")
4447
4448    parser.add_argument("--interval", type=str, default="hour", help="Option: available values are `1min`, `5min`, `15min`, `hour` and `day`. Used only with `--history` key. This is time period of one candle. Default: `hour` for every history candles.")
4449    parser.add_argument("--only-missing", action="store_true", default=False, help="Option: if history file define by `--output` key then add only last missing candles, do not request all history length. `False` by default.")
4450    parser.add_argument("--csv-sep", type=str, default=",", help="Option: separator if csv-file is used, `,` by default.")
4451
4452    parser.add_argument("--debug-level", "--log-level", "--verbosity", "-v", type=int, default=20, help="Option: showing STDOUT messages of minimal debug level, e.g. 10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50 = CRITICAL. INFO (20) by default.")
4453    parser.add_argument("--more", "--more-debug", action="store_true", default=False, help="Option: `--debug-level` key only switch log level verbosity, but in addition `--more` key enable all debug information, such as net request and response headers in all methods.")
4454
4455    # --- commands:
4456
4457    parser.add_argument("--version", "--ver", action="store_true", help="Action: shows current semantic version, looks like `major.minor.buildnumber`. If TKSBrokerAPI not installed via pip, then used local build number `.dev0`.")
4458
4459    parser.add_argument("--list", "-l", action="store_true", help="Action: get and print all available instruments and some information from broker server. Also, you can define `--output` key to save list of instruments to file, default: `instruments.md`.")
4460    parser.add_argument("--list-xlsx", "-x", action="store_true", help="Action: get all available instruments from server for current account and save raw data into xlsx-file for further used by data scientists or stock analytics, default: `dump.xlsx`.")
4461    parser.add_argument("--bonds-xlsx", "-b", type=str, nargs="*", help="Action: get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc. And then export data to XLSX-file, default: `ext-bonds.xlsx` or you can change it with `--output` key. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4462    parser.add_argument("--search", "-s", type=str, nargs=1, help="Action: search for an instruments by part of the name, ticker or FIGI. Also, you can define `--output` key to save results to file, default: `search-results.md`.")
4463    parser.add_argument("--info", "-i", action="store_true", help="Action: get information from broker server about instrument by it's ticker or FIGI. `--ticker` key or `--figi` key must be defined!")
4464    parser.add_argument("--calendar", "-c", type=str, nargs="*", help="Action: show bonds payment calendar as a table. Calendar build for one or more tickers or FIGIs, or for all bonds if only key present. If the `--output` key present then calendar saves to file, default: `calendar.md`. Also, created XLSX-file with bond payments calendar for further used by data scientists or stock analytics, `calendar.xlsx` by default. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4465    parser.add_argument("--price", action="store_true", help="Action: show actual price list for current instrument. Also, you can use `--depth` key. `--ticker` key or `--figi` key must be defined!")
4466    parser.add_argument("--prices", "-p", type=str, nargs="+", help="Action: get and print current prices for list of given instruments (by it's tickers or by FIGIs). WARNING! This is too long operation if you request a lot of instruments! Also, you can define `--output` key to save list of prices to file, default: `prices.md`.")
4467
4468    parser.add_argument("--overview", "-o", action="store_true", help="Action: shows all open positions, orders and some statistics. Also, you can define `--output` key to save this information to file, default: `overview.md`.")
4469    parser.add_argument("--overview-digest", action="store_true", help="Action: shows a short digest of the portfolio status. Also, you can define `--output` key to save this information to file, default: `overview-digest.md`.")
4470    parser.add_argument("--overview-positions", action="store_true", help="Action: shows only open positions. Also, you can define `--output` key to save this information to file, default: `overview-positions.md`.")
4471    parser.add_argument("--overview-orders", action="store_true", help="Action: shows only sections of open limits and stop orders. Also, you can define `--output` key to save orders to file, default: `overview-orders.md`.")
4472    parser.add_argument("--overview-analytics", action="store_true", help="Action: shows only the analytics section and the distribution of the portfolio by various categories. Also, you can define `--output` key to save this information to file, default: `overview-analytics.md`.")
4473
4474    parser.add_argument("--deals", "-d", type=str, nargs="*", help="Action: show all deals between two given dates. Start day may be an integer number: -1, -2, -3 days ago. Also, you can use keywords: `today`, `yesterday` (-1), `week` (-7), `month` (-30) and `year` (-365). Dates format must be: `%%Y-%%m-%%d`, e.g. 2020-02-03. With `--no-cancelled` key information about cancelled operations will be removed from the deals report. Also, you can define `--output` key to save all deals to file, default: `deals.md`.")
4475    parser.add_argument("--history", type=str, nargs="*", help="Action: get last history candles of the current instrument defined by `--ticker` or `--figi` (FIGI id) keys. History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`. This action may be used together with the `--render-chart` key. Also, you can define `--output` key to save history candlesticks to file.")
4476    parser.add_argument("--load-history", type=str, help="Action: try to load history candles from given csv-file as a Pandas Dataframe and print it in to the console. This action may be used together with the `--render-chart` key.")
4477    parser.add_argument("--render-chart", type=str, help="Action: render candlesticks chart. This key may only used with `--history` or `--load-history` together. Action has 1 parameter with two possible string values: `interact` (`i`) or `non-interact` (`ni`).")
4478
4479    parser.add_argument("--trade", nargs="*", help="Action: universal action to open market position for defined ticker or FIGI. You must specify 1-5 parameters: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. See examples in readme.")
4480    parser.add_argument("--buy", nargs="*", help="Action: immediately open BUY market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4481    parser.add_argument("--sell", nargs="*", help="Action: immediately open SELL market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4482
4483    parser.add_argument("--order", nargs="*", help="Action: universal action to open limit or stop-order in any directions. You must specify 4-7 parameters: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]]. See examples in readme.")
4484    parser.add_argument("--buy-limit", type=float, nargs=2, help="Action: open pending BUY limit-order (below current price). You must specify only 2 parameters: [lots] [target price] to open BUY limit-order. If you try to create `Buy` limit-order above current price then broker immediately open `Buy` market order, such as if you do simple `--buy` operation!")
4485    parser.add_argument("--sell-limit", type=float, nargs=2, help="Action: open pending SELL limit-order (above current price). You must specify only 2 parameters: [lots] [target price] to open SELL limit-order. If you try to create `Sell` limit-order below current price then broker immediately open `Sell` market order, such as if you do simple `--sell` operation!")
4486    parser.add_argument("--buy-stop", nargs="*", help="Action: open BUY stop-order. You must specify at least 2 parameters: [lots] [target price] to open BUY stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4487    parser.add_argument("--sell-stop", nargs="*", help="Action: open SELL stop-order. You must specify at least 2 parameters: [lots] [target price] to open SELL stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4488    # parser.add_argument("--buy-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending BUY limit-orders (below current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4489    # parser.add_argument("--sell-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending SELL limit-orders (above current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4490
4491    parser.add_argument("--close-order", "--cancel-order", type=str, nargs=1, help="Action: close only one order by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4492    parser.add_argument("--close-orders", "--cancel-orders", type=str, nargs="+", help="Action: close one or list of orders by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4493    parser.add_argument("--close-trade", "--cancel-trade", action="store_true", help="Action: close only one position for instrument defined by `--ticker` (high priority) or `--figi` keys, including for currencies tickers.")
4494    parser.add_argument("--close-trades", "--cancel-trades", type=str, nargs="+", help="Action: close positions for list of tickers or FIGIs, including for currencies tickers or FIGIs.")
4495    parser.add_argument("--close-all", "--cancel-all", type=str, nargs="*", help="Action: close all available (not blocked) opened trades and orders, excluding for currencies. Also you can select one or more keywords case insensitive to specify trades type: `orders`, `shares`, `bonds`, `etfs` and `futures`, but not `currencies`. Currency positions you must closes manually using `--buy`, `--sell`, `--close-trade` or `--close-trades` operations.")
4496
4497    parser.add_argument("--limits", "--withdrawal-limits", "-w", action="store_true", help="Action: show table of funds available for withdrawal for current `accountId`. You can change `accountId` with the key `--account-id`. Also, you can define `--output` key to save this information to file, default: `limits.md`.")
4498    parser.add_argument("--user-info", "-u", action="store_true", help="Action: show all available user's data (`accountId`s, common user information, margin status and tariff connections limit). Also, you can define `--output` key to save this information to file, default: `user-info.md`.")
4499    parser.add_argument("--account", "--accounts", "-a", action="store_true", help="Action: show simple table with all available user accounts. Also, you can define `--output` key to save this information to file, default: `accounts.md`.")
4500
4501    cmdArgs = parser.parse_args()
4502    return cmdArgs
4503
4504
4505def Main(**kwargs):
4506    """
4507    Main function for work with TKSBrokerAPI in the console.
4508
4509    See examples:
4510    - in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
4511    - in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md
4512    """
4513    args = Args(**kwargs) if kwargs else ParseArgs()  # get and parse command-line parameters or use **kwarg parameters
4514
4515    if args.debug_level:
4516        uLogger.level = 10  # always debug level by default
4517        uLogger.handlers[0].level = args.debug_level  # level for STDOUT
4518
4519    exitCode = 0
4520    start = datetime.now(tzutc())
4521    uLogger.debug("=-" * 50)
4522    uLogger.debug(">>> TKSBrokerAPI module started at: [{}] UTC, it is [{}] local time".format(
4523        start.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4524        start.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4525    ))
4526
4527    # trying to calculate full current version:
4528    buildVersion = __version__
4529    try:
4530        v = version("tksbrokerapi")
4531        buildVersion = v if v.startswith(buildVersion) else buildVersion + ".dev0"  # set version as major.minor.dev0 if run as local build or local script
4532
4533    except Exception:
4534        buildVersion = __version__ + ".dev0"  # if an errors occurred then also set version as major.minor.dev0
4535
4536    uLogger.debug("TKSBrokerAPI major.minor.build version used: [{}]".format(buildVersion))
4537    uLogger.debug("Host CPU count: [{}]".format(CPU_COUNT))
4538
4539    try:
4540        if args.version:
4541            print("TKSBrokerAPI {}".format(buildVersion))
4542            uLogger.debug("User requested current TKSBrokerAPI major.minor.build version: [{}]".format(buildVersion))
4543
4544        else:
4545            # Init class for trading with Tinkoff Broker:
4546            trader = TinkoffBrokerServer(
4547                token=args.token,
4548                accountId=args.account_id,
4549                useCache=not args.no_cache,
4550            )
4551
4552            # --- set some options:
4553
4554            if args.more:
4555                trader.moreDebug = True
4556                uLogger.warning("More debug info mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
4557
4558            if args.ticker:
4559                if args.ticker in trader.aliasesKeys:
4560                    trader.ticker = trader.aliases[args.ticker]  # Replace some tickers with its aliases
4561
4562                else:
4563                    trader.ticker = args.ticker
4564
4565            if args.figi:
4566                trader.figi = args.figi
4567
4568            if args.depth is not None:
4569                trader.depth = args.depth
4570
4571            # --- do one command:
4572
4573            if args.list:
4574                if args.output is not None:
4575                    trader.instrumentsFile = args.output
4576
4577                trader.ShowInstrumentsInfo(show=True)
4578
4579            elif args.list_xlsx:
4580                trader.DumpInstrumentsAsXLSX(forceUpdate=False)
4581
4582            elif args.bonds_xlsx is not None:
4583                if args.output is not None:
4584                    trader.bondsXLSXFile = args.output
4585
4586                if len(args.bonds_xlsx) == 0:
4587                    trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=True)  # request bonds with all available tickers
4588
4589                else:
4590                    trader.ExtendBondsData(instruments=args.bonds_xlsx, xlsx=True)  # request list of given bonds
4591
4592            elif args.search:
4593                if args.output is not None:
4594                    trader.searchResultsFile = args.output
4595
4596                trader.SearchInstruments(pattern=args.search[0], show=True)
4597
4598            elif args.info:
4599                if not (args.ticker or args.figi):
4600                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4601                    raise Exception("Ticker or FIGI required")
4602
4603                if args.output is not None:
4604                    trader.infoFile = args.output
4605
4606                if args.ticker:
4607                    trader.SearchByTicker(requestPrice=True, show=True)  # show info and current prices by ticker name
4608
4609                else:
4610                    trader.SearchByFIGI(requestPrice=True, show=True)  # show info and current prices by FIGI id
4611
4612            elif args.calendar is not None:
4613                if args.output is not None:
4614                    trader.calendarFile = args.output
4615
4616                if len(args.calendar) == 0:
4617                    bondsData = trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=False)  # request bonds with all available tickers
4618
4619                else:
4620                    bondsData = trader.ExtendBondsData(instruments=args.calendar, xlsx=False)  # request list of given bonds
4621
4622                trader.ShowBondsCalendar(extBonds=bondsData, show=True)  # shows bonds payment calendar only
4623
4624            elif args.price:
4625                if not (args.ticker or args.figi):
4626                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4627                    raise Exception("Ticker or FIGI required")
4628
4629                trader.GetCurrentPrices(show=True)
4630
4631            elif args.prices is not None:
4632                if args.output is not None:
4633                    trader.pricesFile = args.output
4634
4635                trader.GetListOfPrices(instruments=args.prices, show=True)  # WARNING: too long wait for a lot of instruments prices
4636
4637            elif args.overview:
4638                if args.output is not None:
4639                    trader.overviewFile = args.output
4640
4641                trader.Overview(show=True, details="full")
4642
4643            elif args.overview_digest:
4644                if args.output is not None:
4645                    trader.overviewDigestFile = args.output
4646
4647                trader.Overview(show=True, details="digest")
4648
4649            elif args.overview_positions:
4650                if args.output is not None:
4651                    trader.overviewPositionsFile = args.output
4652
4653                trader.Overview(show=True, details="positions")
4654
4655            elif args.overview_orders:
4656                if args.output is not None:
4657                    trader.overviewOrdersFile = args.output
4658
4659                trader.Overview(show=True, details="orders")
4660
4661            elif args.overview_analytics:
4662                if args.output is not None:
4663                    trader.overviewAnalyticsFile = args.output
4664
4665                trader.Overview(show=True, details="analytics")
4666
4667            elif args.deals is not None:
4668                if args.output is not None:
4669                    trader.reportFile = args.output
4670
4671                if 0 <= len(args.deals) < 3:
4672                    trader.Deals(
4673                        start=args.deals[0] if len(args.deals) >= 1 else None,
4674                        end=args.deals[1] if len(args.deals) == 2 else None,
4675                        show=True,  # Always show deals report in console
4676                        showCancelled=not args.no_cancelled,  # If --no-cancelled key then remove cancelled operations from the deals report. False by default.
4677                    )
4678
4679                else:
4680                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
4681                    raise Exception("Incorrect value")
4682
4683            elif args.history is not None:
4684                if args.output is not None:
4685                    trader.historyFile = args.output
4686
4687                if 0 <= len(args.history) < 3:
4688                    dataReceived = trader.History(
4689                        start=args.history[0] if len(args.history) >= 1 else None,
4690                        end=args.history[1] if len(args.history) == 2 else None,
4691                        interval="hour" if args.interval is None or not args.interval else args.interval,
4692                        onlyMissing=False if args.only_missing is None or not args.only_missing else args.only_missing,
4693                        csvSep="," if args.csv_sep is None or not args.csv_sep else args.csv_sep,
4694                        show=True,  # shows all downloaded candles in console
4695                    )
4696
4697                    if args.render_chart is not None and dataReceived is not None:
4698                        iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
4699
4700                        trader.ShowHistoryChart(
4701                            candles=dataReceived,
4702                            interact=iChart,
4703                            openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
4704                        )
4705
4706                else:
4707                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
4708                    raise Exception("Incorrect value")
4709
4710            elif args.load_history is not None:
4711                histData = trader.LoadHistory(filePath=args.load_history)  # load data from file and show history in console
4712
4713                if args.render_chart is not None and histData is not None:
4714                    iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
4715                    trader.ticker = os.path.basename(args.load_history)  # use filename as ticker name for PriceGenerator's chart
4716
4717                    trader.ShowHistoryChart(
4718                        candles=histData,
4719                        interact=iChart,
4720                        openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
4721                    )
4722
4723            elif args.trade is not None:
4724                if 1 <= len(args.trade) <= 5:
4725                    trader.Trade(
4726                        operation=args.trade[0],
4727                        lots=int(args.trade[1]) if len(args.trade) >= 2 else 1,
4728                        tp=float(args.trade[2]) if len(args.trade) >= 3 else 0.,
4729                        sl=float(args.trade[3]) if len(args.trade) >= 4 else 0.,
4730                        expDate=args.trade[4] if len(args.trade) == 5 else "Undefined",
4731                    )
4732
4733                else:
4734                    uLogger.error("You must specify 1-5 parameters to open trade: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4735
4736            elif args.buy is not None:
4737                if 0 <= len(args.buy) <= 4:
4738                    trader.Buy(
4739                        lots=int(args.buy[0]) if len(args.buy) >= 1 else 1,
4740                        tp=float(args.buy[1]) if len(args.buy) >= 2 else 0.,
4741                        sl=float(args.buy[2]) if len(args.buy) >= 3 else 0.,
4742                        expDate=args.buy[3] if len(args.buy) == 4 else "Undefined",
4743                    )
4744
4745                else:
4746                    uLogger.error("You must specify 0-4 parameters to open buy position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4747
4748            elif args.sell is not None:
4749                if 0 <= len(args.sell) <= 4:
4750                    trader.Sell(
4751                        lots=int(args.sell[0]) if len(args.sell) >= 1 else 1,
4752                        tp=float(args.sell[1]) if len(args.sell) >= 2 else 0.,
4753                        sl=float(args.sell[2]) if len(args.sell) >= 3 else 0.,
4754                        expDate=args.sell[3] if len(args.sell) == 4 else "Undefined",
4755                    )
4756
4757                else:
4758                    uLogger.error("You must specify 0-4 parameters to open sell position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4759
4760            elif args.order:
4761                if 4 <= len(args.order) <= 7:
4762                    trader.Order(
4763                        operation=args.order[0],
4764                        orderType=args.order[1],
4765                        lots=int(args.order[2]),
4766                        targetPrice=float(args.order[3]),
4767                        limitPrice=float(args.order[4]) if len(args.order) >= 5 else 0.,
4768                        stopType=args.order[5] if len(args.order) >= 6 else "Limit",
4769                        expDate=args.order[6] if len(args.order) == 7 else "Undefined",
4770                    )
4771
4772                else:
4773                    uLogger.error("You must specify 4-7 parameters to open order: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]]. See: `python TKSBrokerAPI.py --help`")
4774
4775            elif args.buy_limit:
4776                trader.BuyLimit(lots=int(args.buy_limit[0]), targetPrice=args.buy_limit[1])
4777
4778            elif args.sell_limit:
4779                trader.SellLimit(lots=int(args.sell_limit[0]), targetPrice=args.sell_limit[1])
4780
4781            elif args.buy_stop:
4782                if 2 <= len(args.buy_stop) <= 7:
4783                    trader.BuyStop(
4784                        lots=int(args.buy_stop[0]),
4785                        targetPrice=float(args.buy_stop[1]),
4786                        limitPrice=float(args.buy_stop[2]) if len(args.buy_stop) >= 3 else 0.,
4787                        stopType=args.buy_stop[3] if len(args.buy_stop) >= 4 else "Limit",
4788                        expDate=args.buy_stop[4] if len(args.buy_stop) == 5 else "Undefined",
4789                    )
4790
4791                else:
4792                    uLogger.error("You must specify 2-5 parameters for buy stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4793
4794            elif args.sell_stop:
4795                if 2 <= len(args.sell_stop) <= 7:
4796                    trader.SellStop(
4797                        lots=int(args.sell_stop[0]),
4798                        targetPrice=float(args.sell_stop[1]),
4799                        limitPrice=float(args.sell_stop[2]) if len(args.sell_stop) >= 3 else 0.,
4800                        stopType=args.sell_stop[3] if len(args.sell_stop) >= 4 else "Limit",
4801                        expDate=args.sell_stop[4] if len(args.sell_stop) == 5 else "Undefined",
4802                    )
4803
4804                else:
4805                    uLogger.error("You must specify 2-5 parameters for sell stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: python TKSBrokerAPI.py --help")
4806
4807            # elif args.buy_order_grid is not None:
4808            #     # update order grid work with api v2
4809            #     if len(args.buy_order_grid) == 2:
4810            #         orderParams = trader.ParseOrderParameters(operation="Buy", **dict(kw.split('=') for kw in args.buy_order_grid))
4811            #
4812            #         for order in orderParams:
4813            #             trader.Order(operation="Buy", lots=order["lot"], price=order["price"])
4814            #
4815            #     else:
4816            #         uLogger.error("To open grid of pending BUY limit-orders (below current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
4817            #
4818            # elif args.sell_order_grid is not None:
4819            #     # update order grid work with api v2
4820            #     if len(args.sell_order_grid) >= 2:
4821            #         orderParams = trader.ParseOrderParameters(operation="Sell", **dict(kw.split('=') for kw in args.sell_order_grid))
4822            #
4823            #         for order in orderParams:
4824            #             trader.Order(operation="Sell", lots=order["lot"], price=order["price"])
4825            #
4826            #     else:
4827            #         uLogger.error("To open grid of pending SELL limit-orders (above current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
4828
4829            elif args.close_order is not None:
4830                trader.CloseOrders(args.close_order)  # close only one order
4831
4832            elif args.close_orders is not None:
4833                trader.CloseOrders(args.close_orders)  # close list of orders
4834
4835            elif args.close_trade:
4836                if not (args.ticker or args.figi):
4837                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4838                    raise Exception("Ticker or FIGI required")
4839
4840                if args.ticker:
4841                    trader.CloseTrades([args.ticker])  # close only one trade by ticker (priority)
4842
4843                else:
4844                    trader.CloseTrades([args.figi])  # close only one trade by FIGI
4845
4846            elif args.close_trades is not None:
4847                trader.CloseTrades(args.close_trades)  # close trades for list of tickers
4848
4849            elif args.close_all is not None:
4850                trader.CloseAll(*args.close_all)
4851
4852            elif args.limits:
4853                if args.output is not None:
4854                    trader.withdrawalLimitsFile = args.output
4855
4856                trader.OverviewLimits(show=True)
4857
4858            elif args.user_info:
4859                if args.output is not None:
4860                    trader.userInfoFile = args.output
4861
4862                trader.OverviewUserInfo(show=True)
4863
4864            elif args.account:
4865                if args.output is not None:
4866                    trader.userAccountsFile = args.output
4867
4868                trader.OverviewAccounts(show=True)
4869
4870            else:
4871                uLogger.error("There is no command to execute! One of the possible commands must be selected. See help with `--help` key.")
4872                raise Exception("There is no command to execute")
4873
4874    except Exception:
4875        trace = tb.format_exc()
4876        for e in ["socket.gaierror", "nodename nor servname provided", "or not known", "NewConnectionError", "[Errno 8]", "Failed to establish a new connection"]:
4877            if e in trace:
4878                uLogger.error("Check your Internet connection! Failed to establish connection to broker server!")
4879                break
4880
4881        uLogger.debug(trace)
4882        uLogger.debug("Please, check issues or request a new one at https://github.com/Tim55667757/TKSBrokerAPI/issues")
4883        exitCode = 255  # an error occurred, must be open a ticket for this issue
4884
4885    finally:
4886        finish = datetime.now(tzutc())
4887
4888        if exitCode == 0:
4889            if args.more:
4890                uLogger.debug("All operations were finished success (summary code is 0).")
4891
4892        else:
4893            uLogger.error("An issue occurred with TKSBrokerAPI module! See full debug log in [{}] or run TKSBrokerAPI once again with the key `--debug-level 10`. Summary code: {}".format(
4894                os.path.abspath(uLog.defaultLogFile), exitCode,
4895            ))
4896
4897        uLogger.debug(">>> TKSBrokerAPI module work duration: [{}]".format(finish - start))
4898        uLogger.debug(">>> TKSBrokerAPI module finished: [{} UTC], it is [{}] local time".format(
4899            finish.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4900            finish.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4901        ))
4902        uLogger.debug("=-" * 50)
4903
4904        if not kwargs:
4905            sys.exit(exitCode)
4906
4907        else:
4908            return exitCode
4909
4910
4911if __name__ == "__main__":
4912    Main()